From 51fe319faf4399fd027f8b32d1c425200b911e44 Mon Sep 17 00:00:00 2001
From: Tyler Anton <mtyleranton@gmail.com>
Date: Sat, 7 Mar 2015 21:52:18 -0500
Subject: [PATCH] docs: add return value for sync fs functions

Clarify that synchronous functions in fs with no return value return
undefined.

Specify that fs.openSync() returns an integer and fs.existsSync()
returns true or false.

Fixes #9313

PR: #9359
PR-URL: https://github.com/joyent/node/pull/9359
Reviewed-By: Julien Gilli <julien.gilli@joyent.com>
---
 doc/api/fs.markdown | 53 ++++++++++++++++++++++++++-------------------
 1 file changed, 31 insertions(+), 22 deletions(-)

diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown
index f886b73dc7e..56d66ba4e96 100644
--- a/doc/api/fs.markdown
+++ b/doc/api/fs.markdown
@@ -77,7 +77,7 @@ to the completion callback.
 
 ## fs.renameSync(oldPath, newPath)
 
-Synchronous rename(2).
+Synchronous rename(2). Returns `undefined`.
 
 ## fs.ftruncate(fd, len, callback)
 
@@ -86,7 +86,7 @@ given to the completion callback.
 
 ## fs.ftruncateSync(fd, len)
 
-Synchronous ftruncate(2).
+Synchronous ftruncate(2). Returns `undefined`.
 
 ## fs.truncate(path, len, callback)
 
@@ -95,7 +95,7 @@ given to the completion callback.
 
 ## fs.truncateSync(path, len)
 
-Synchronous truncate(2).
+Synchronous truncate(2). Returns `undefined`.
 
 ## fs.chown(path, uid, gid, callback)
 
@@ -104,7 +104,7 @@ to the completion callback.
 
 ## fs.chownSync(path, uid, gid)
 
-Synchronous chown(2).
+Synchronous chown(2). Returns `undefined`.
 
 ## fs.fchown(fd, uid, gid, callback)
 
@@ -113,7 +113,7 @@ to the completion callback.
 
 ## fs.fchownSync(fd, uid, gid)
 
-Synchronous fchown(2).
+Synchronous fchown(2). Returns `undefined`.
 
 ## fs.lchown(path, uid, gid, callback)
 
@@ -122,7 +122,7 @@ to the completion callback.
 
 ## fs.lchownSync(path, uid, gid)
 
-Synchronous lchown(2).
+Synchronous lchown(2). Returns `undefined`.
 
 ## fs.chmod(path, mode, callback)
 
@@ -131,7 +131,7 @@ to the completion callback.
 
 ## fs.chmodSync(path, mode)
 
-Synchronous chmod(2).
+Synchronous chmod(2). Returns `undefined`.
 
 ## fs.fchmod(fd, mode, callback)
 
@@ -140,7 +140,7 @@ are given to the completion callback.
 
 ## fs.fchmodSync(fd, mode)
 
-Synchronous fchmod(2).
+Synchronous fchmod(2). Returns `undefined`.
 
 ## fs.lchmod(path, mode, callback)
 
@@ -151,7 +151,7 @@ Only available on Mac OS X.
 
 ## fs.lchmodSync(path, mode)
 
-Synchronous lchmod(2).
+Synchronous lchmod(2). Returns `undefined`.
 
 ## fs.stat(path, callback)
 
@@ -191,7 +191,7 @@ the completion callback.
 
 ## fs.linkSync(srcpath, dstpath)
 
-Synchronous link(2).
+Synchronous link(2). Returns `undefined`.
 
 ## fs.symlink(srcpath, dstpath, [type], callback)
 
@@ -204,7 +204,7 @@ Note that Windows junction points require the destination path to be absolute.
 
 ## fs.symlinkSync(srcpath, dstpath, [type])
 
-Synchronous symlink(2).
+Synchronous symlink(2). Returns `undefined`.
 
 ## fs.readlink(path, callback)
 
@@ -241,7 +241,7 @@ to the completion callback.
 
 ## fs.unlinkSync(path)
 
-Synchronous unlink(2).
+Synchronous unlink(2). Returns `undefined`.
 
 ## fs.rmdir(path, callback)
 
@@ -250,7 +250,7 @@ to the completion callback.
 
 ## fs.rmdirSync(path)
 
-Synchronous rmdir(2).
+Synchronous rmdir(2). Returns `undefined`.
 
 ## fs.mkdir(path, [mode], callback)
 
@@ -259,7 +259,7 @@ to the completion callback. `mode` defaults to `0777`.
 
 ## fs.mkdirSync(path, [mode])
 
-Synchronous mkdir(2).
+Synchronous mkdir(2). Returns `undefined`.
 
 ## fs.readdir(path, callback)
 
@@ -279,7 +279,7 @@ to the completion callback.
 
 ## fs.closeSync(fd)
 
-Synchronous close(2).
+Synchronous close(2). Returns `undefined`.
 
 ## fs.open(path, flags, [mode], callback)
 
@@ -340,19 +340,27 @@ the end of the file.
 
 ## fs.openSync(path, flags, [mode])
 
-Synchronous version of `fs.open()`.
+Synchronous version of `fs.open()`. Returns an integer representing the file
+descriptor.
 
 ## fs.utimes(path, atime, mtime, callback)
-## fs.utimesSync(path, atime, mtime)
 
 Change file timestamps of the file referenced by the supplied path.
 
+## fs.utimesSync(path, atime, mtime)
+
+Synchronous version of `fs.utimes()`. Returns `undefined`.
+
+
 ## fs.futimes(fd, atime, mtime, callback)
-## fs.futimesSync(fd, atime, mtime)
 
 Change the file timestamps of a file referenced by the supplied file
 descriptor.
 
+## fs.futimesSync(fd, atime, mtime)
+
+Synchronous version of `fs.futimes()`. Returns `undefined`.
+
 ## fs.fsync(fd, callback)
 
 Asynchronous fsync(2). No arguments other than a possible exception are given
@@ -360,7 +368,7 @@ to the completion callback.
 
 ## fs.fsyncSync(fd)
 
-Synchronous fsync(2).
+Synchronous fsync(2). Returns `undefined`.
 
 ## fs.write(fd, buffer, offset, length, position, callback)
 
@@ -461,7 +469,7 @@ Example:
 
 ## fs.writeFileSync(filename, data, [options])
 
-The synchronous version of `fs.writeFile`.
+The synchronous version of `fs.writeFile`. Returns `undefined`.
 
 ## fs.appendFile(filename, data, [options], callback)
 
@@ -485,7 +493,7 @@ Example:
 
 ## fs.appendFileSync(filename, data, [options])
 
-The synchronous version of `fs.appendFile`.
+The synchronous version of `fs.appendFile`. Returns `undefined`.
 
 ## fs.watchFile(filename, [options], listener)
 
@@ -605,7 +613,8 @@ and handle the error when it's not there.
 
 ## fs.existsSync(path)
 
-Synchronous version of `fs.exists`.
+Synchronous version of `fs.exists()`. Returns `true` if the file exists,
+`false` otherwise.
 
 ## Class: fs.Stats