doc: added note to fs.watchFile on previousStat

Explains the expected behavior of previousStat in fs.watchFile() when
a watched file disappears and reappears.

PR-URL: #16099
Fixes: #15364
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Claudio Rodriguez <[email protected]>
Reviewed-By: Gireesh Punathil <[email protected]>
Reviewed-By: Ben Noordhuis <[email protected]>

Author: niveditn

doc/api/fs.md

@@ -1925,6 +1925,15 @@ you need to compare `curr.mtime` and `prev.mtime`.
 `fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and
 `fs.unwatchFile` when possible.
 
+*Note:* When a file being watched by `fs.watchFile()` disappears and reappears,
+then the `previousStat` reported in the second callback event (the file's
+reappearance) will be the same as the `previousStat` of the first callback
+event (its disappearance).
+
+This happens when:
+- the file is deleted, followed by a restore
+- the file is renamed twice - the second time back to its original name
+
 ## fs.write(fd, buffer[, offset[, length[, position]]], callback)
 <!-- YAML
 added: v0.0.2