Skip to content

Commit

Permalink
doc: improve documentation of fs sync methods
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
iwko authored and targos committed Jul 10, 2018
1 parent b8ba003 commit cd77d87
Showing 1 changed file with 48 additions and 15 deletions.
63 changes: 48 additions & 15 deletions doc/api/fs.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down

0 comments on commit cd77d87

Please sign in to comment.