doc: Stability and Caveats for fs.watch/watchFile

1 files changed, 36 insertions, 2 deletions

diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown
index 2c7f43674f7..822e03af2f2 100644
--- a/doc/api/fs.markdown
+++ b/doc/api/fs.markdown
@@ -391,6 +391,8 @@ The synchronous version of `fs.writeFile`.
 
 ## fs.watchFile(filename, [options], listener)
 
+   Stability: 2 - Unstable.  Use fs.watch instead, if available.
+
 Watch for changes on `filename`. The callback `listener` will be called each
 time the file is accessed.
 
@@ -417,10 +419,14 @@ you need to compare `curr.mtime` and `prev.mtime`.
 
 ## fs.unwatchFile(filename)
 
+   Stability: 2 - Unstable.  Use fs.watch instead, if available.
+
 Stop watching for changes on `filename`.
 
 ## fs.watch(filename, [options], listener)
 
+   Stability: 2 - Unstable.  Not available on all platforms.
+
 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).
 
@@ -433,8 +439,36 @@ The listener callback gets two arguments `(event, filename)`.  `event` is either
 'rename' or 'change', and `filename` is the name of the file which triggered
 the event.
 
-***Warning:***
-Providing `filename` argument in the callback is not supported
+### Caveats
+
+<!--type=misc-->
+
+The `fs.watch` API is not 100% consistent across platforms, and is
+unavailable in some situations.
+
+#### Availability
+
+<!--type=misc-->
+
+This feature depends on the underlying operating system providing a way
+to be notified of filesystem changes.
+
+* On Linux systems, this uses `inotify`.
+* On BSD systems (including OS X), this uses `kqueue`.
+* On SunOS systems (including Solaris and SmartOS), this uses `event ports`.
+* On Windows systems, this feature depends on `ReadDirectoryChangesW`.
+
+If the underlying functionality is not available for some reason, then
+`fs.watch` will not be able to function.  You can still use
+`fs.watchFile`, which uses stat polling, but it is slower and less
+reliable.
+
+#### Filename Argument
+
+<!--type=misc-->
+
+When watching a directory,
+providing `filename` argument in the callback is not supported
 on every platform (currently it's only supported on Linux and Windows).  Even
 on supported platforms `filename` is not always guaranteed to be provided.
 Therefore, don't assume that `filename` argument is always provided in the