doc: document intention and dangers of fs module Buffer API

PR-URL: #6020
Reviewed-By: James M Snell <[email protected]>

Author: seishun

doc/api/fs.markdown

@@ -94,6 +94,18 @@ Error: EISDIR, read
     <etc.>
 ```
 
+## Buffer API
+
+`fs` functions support passing and receiving paths as both strings
+and Buffers. The latter is intended to make it possible to work with
+filesystems that allow for non-UTF-8 filenames. For most typical
+uses, working with paths as Buffers will be unnecessary, as the string
+API converts to and from UTF-8 automatically.
+
+*Note* that on certain file systems (such as NTFS and HFS+) filenames
+will always be encoded as UTF-8. On such file systems, passing
+non-UTF-8 encoded Buffers to `fs` functions will not work as expected.
+
 ## Class: fs.FSWatcher
 
 Objects returned from `fs.watch()` are of this type.