doc: improve documentation of fs sync methods

Add links to async methods and make wording consistent. PR-URL: #21243 Refs: #21197 Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Jamie Davis <davisjam@vt.edu> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
nodejs · Jul 10, 2018 · cd77d8782a241f5b4e4d65c1f8852be57f8edbef · cd77d87
1 parent b8ba003
commit cd77d8782a241f5b4e4d65c1f8852be57f8edbef
Showing with 48 additions and 15 deletions.

+48 −15 doc/api/fs.md
diff --git a/doc/api/fs.md b/doc/api/fs.md
@@ -1137,8 +1137,8 @@ changes:
 * `path` {string|Buffer|URL}
 * `mode` {integer}
 
-Synchronously changes the permissions of a file. Returns `undefined`.
-This is the synchronous version of [`fs.chmod()`][].
+For detailed information, see the documentation of the asynchronous version of
+this API: [`fs.chmod()`][].
 
 See also: chmod(2).
 
@@ -1562,13 +1562,16 @@ changes:
 * `path` {string|Buffer|URL}
 * Returns: {boolean}
 
-Synchronous version of [`fs.exists()`][].
 Returns `true` if the path exists, `false` otherwise.
 
+For detailed information, see the documentation of the asynchronous version of
+this API: [`fs.exists()`][].
+
 `fs.exists()` is deprecated, but `fs.existsSync()` is not. The `callback`
 parameter to `fs.exists()` accepts parameters that are inconsistent with other
 Node.js callbacks. `fs.existsSync()` does not use a callback.
 
+
 ## fs.fchmod(fd, mode, callback)
 <!-- YAML
 added: v0.4.7
@@ -1815,7 +1818,10 @@ added: v0.8.6
 * `fd` {integer}
 * `len` {integer} **Default:** `0`
 
-Synchronous ftruncate(2). Returns `undefined`.
+Returns `undefined`.
+
+For detailed information, see the documentation of the asynchronous version of
+this API: [`fs.ftruncate()`][].
 
 ## fs.futimes(fd, atime, mtime, callback)
 <!-- YAML
@@ -2165,8 +2171,10 @@ added: v5.10.0
   * `encoding` {string} **Default:** `'utf8'`
 * Returns: {string}
 
-The synchronous version of [`fs.mkdtemp()`][]. Returns the created
-folder path.
+Returns the created folder path.
+
+For detailed information, see the documentation of the asynchronous version of
+this API: [`fs.mkdtemp()`][].
 
 The optional `options` argument can be a string specifying an encoding, or an
 object with an `encoding` property specifying the character encoding to use.
@@ -2222,8 +2230,10 @@ changes:
 * `mode` {integer} **Default:** `0o666`
 * Returns: {number}
 
-Synchronous version of [`fs.open()`][]. Returns an integer representing the file
-descriptor.
+Returns an integer representing the file descriptor.
+
+For detailed information, see the documentation of the asynchronous version of
+this API: [`fs.open()`][].
 
 ## fs.read(fd, buffer, offset, length, position, callback)
 <!-- YAML
@@ -2421,7 +2431,10 @@ changes:
   * `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`.
 * Returns: {string|Buffer}
 
-Synchronous version of [`fs.readFile()`][]. Returns the contents of the `path`.
+Returns the contents of the `path`.
+
+For detailed information, see the documentation of the asynchronous version of
+this API: [`fs.readFile()`][].
 
 If the `encoding` option is specified then this function returns a
 string. Otherwise it returns a buffer.
@@ -2509,7 +2522,10 @@ changes:
 * `position` {integer}
 * Returns: {number}
 
-Synchronous version of [`fs.read()`][]. Returns the number of `bytesRead`.
+Returns the number of `bytesRead`.
+
+For detailed information, see the documentation of the asynchronous version of
+this API: [`fs.read()`][].
 
 ## fs.realpath(path[, options], callback)
 <!-- YAML
@@ -2624,7 +2640,10 @@ changes:
   * `encoding` {string} **Default:** `'utf8'`
 * Returns: {string|Buffer}
 
-Synchronous version of [`fs.realpath()`][]. Returns the resolved pathname.
+Returns the resolved pathname.
+
+For detailed information, see the documentation of the asynchronous version of
+this API: [`fs.realpath()`][].
 
 ## fs.realpathSync.native(path[, options])
 <!-- YAML
@@ -2860,7 +2879,10 @@ changes:
 * `path` {string|Buffer|URL}
 * `type` {string} **Default:** `'file'`
 
-Synchronous symlink(2). Returns `undefined`.
+Returns `undefined`.
+
+For detailed information, see the documentation of the asynchronous version of
+this API: [`fs.symlink()`][].
 
 ## fs.truncate(path[, len], callback)
 <!-- YAML
@@ -3036,7 +3058,10 @@ changes:
 * `atime` {integer}
 * `mtime` {integer}
 
-Synchronous version of [`fs.utimes()`][]. Returns `undefined`.
+Returns `undefined`.
+
+For detailed information, see the documentation of the asynchronous version of
+this API: [`fs.utimes()`][].
 
 ## fs.watch(filename[, options][, listener])
 <!-- YAML
@@ -3387,7 +3412,10 @@ changes:
   * `mode` {integer} **Default:** `0o666`
   * `flag` {string} See [support of file system `flags`][]. **Default:** `'w'`.
 
-The synchronous version of [`fs.writeFile()`][]. Returns `undefined`.
+Returns `undefined`.
+
+For detailed information, see the documentation of the asynchronous version of
+this API: [`fs.writeFile()`][].
 
 ## fs.writeSync(fd, buffer[, offset[, length[, position]]])
 <!-- YAML
@@ -3423,7 +3451,10 @@ changes:
 * `encoding` {string}
 * Returns: {number}
 
-Synchronous versions of [`fs.write()`][]. Returns the number of bytes written.
+Returns the number of bytes written.
+
+For detailed information, see the documentation of the asynchronous version of
+this API: [`fs.write()`][].
 
 ## fs Promises API
 
@@ -4588,6 +4619,7 @@ the file contents.
 [`fs.copyFile()`]: #fs_fs_copyfile_src_dest_flags_callback
 [`fs.exists()`]: fs.html#fs_fs_exists_path_callback
 [`fs.fstat()`]: #fs_fs_fstat_fd_options_callback
+[`fs.ftruncate()`]: #fs_fs_ftruncate_fd_len_callback
 [`fs.futimes()`]: #fs_fs_futimes_fd_atime_mtime_callback
 [`fs.lstat()`]: #fs_fs_lstat_path_options_callback
 [`fs.mkdir()`]: #fs_fs_mkdir_path_mode_callback
@@ -4599,6 +4631,7 @@ the file contents.
 [`fs.realpath()`]: #fs_fs_realpath_path_options_callback
 [`fs.rmdir()`]: #fs_fs_rmdir_path_callback
 [`fs.stat()`]: #fs_fs_stat_path_options_callback
+[`fs.symlink()`]: #fs_fs_symlink_target_path_type_callback
 [`fs.utimes()`]: #fs_fs_utimes_path_atime_mtime_callback
 [`fs.watch()`]: #fs_fs_watch_filename_options_listener
 [`fs.write()`]: #fs_fs_write_fd_buffer_offset_length_position_callback