Doc improvements. Explained the flags of fs.open().

Fixes #1268.

diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown
index 4c37a16..faf1b47 100644 (file)
--- a/doc/api/fs.markdown
+++ b/doc/api/fs.markdown
@@ -255,8 +255,27 @@ Synchronous close(2).
 
 ### fs.open(path, flags, [mode], [callback])
 
-Asynchronous file open. See open(2). Flags can be 'r', 'r+', 'w', 'w+', 'a',
-or 'a+'. `mode` defaults to 0666. The callback gets two arguments `(err, fd)`.
+Asynchronous file open. See open(2). `flags` can be:
+
+* `'r'` - Open file for reading.
+An exception occurs if the file does not exist.
+
+* `'r+'` - Open file for reading and writing. 
+An exception occurs if the file does not exist.
+
+* `'w'` - Open file for writing.
+The file is created (if it does not exist) or truncated (if it exists).
+
+* `'w+'` - Open file for reading and writing.
+The file is created (if it does not exist) or truncated (if it exists).
+
+* `'a'` - Open file for appending.
+The file is created if it does not exist.
+
+* `'a+'` - Open file for reading and appending.
+The file is created if it does not exist.
+
+`mode` defaults to `0666`. The callback gets two arguments `(err, fd)`.
 
 ### fs.openSync(path, flags, [mode])