From f23adbd22f0ac9f781fe9d204814b07b5a9d0ff4 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 22 May 2015 17:01:10 -0700 Subject: [PATCH] doc: clarify stability of fs.watch and relatives Fixes: https://github.com/nodejs/io.js/issues/1754 PR-URL: https://github.com/nodejs/io.js/pull/1775 Reviewed-By: Brendan Ashworth Reviewed-By: Jeremiah Senkpiel --- doc/api/fs.markdown | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown index 398726cea..f7093056c 100644 --- a/doc/api/fs.markdown +++ b/doc/api/fs.markdown @@ -534,8 +534,6 @@ The synchronous version of `fs.appendFile`. ## fs.watchFile(filename[, options], listener) - Stability: 2 - Unstable. Use fs.watch instead, if possible. - Watch for changes on `filename`. The callback `listener` will be called each time the file is accessed. @@ -558,9 +556,11 @@ These stat objects are instances of `fs.Stat`. If you want to be notified when the file was modified, not just accessed you need to compare `curr.mtime` and `prev.mtime`. -## fs.unwatchFile(filename[, listener]) +_Note: `fs.watch` is more efficient than `fs.watchFile` and `fs.unwatchFile`. +`fs.watch` should be used instead of `fs.watchFile` and `fs.unwatchFile` +when possible._ - Stability: 2 - Unstable. Use fs.watch instead, if possible. +## fs.unwatchFile(filename[, listener]) Stop watching for changes on `filename`. If `listener` is specified, only that particular listener is removed. Otherwise, *all* listeners are removed and you @@ -569,9 +569,11 @@ have effectively stopped watching `filename`. Calling `fs.unwatchFile()` with a filename that is not being watched is a no-op, not an error. -## fs.watch(filename[, options][, listener]) +_Note: `fs.watch` is more efficient than `fs.watchFile` and `fs.unwatchFile`. +`fs.watch` should be used instead of `fs.watchFile` and `fs.unwatchFile` +when possible._ - Stability: 2 - Unstable. +## fs.watch(filename[, options][, listener]) Watch for changes on `filename`, where `filename` is either a file or a directory. The returned object is a [fs.FSWatcher](#fs_class_fs_fswatcher).