Skip to content

Commit

Permalink
doc: clarify fs.write[Sync]() descriptions
Browse files Browse the repository at this point in the history
1. All default values for optional `encoding` parameters
   were documented except for the one in `fs.write(fd, string...)`
   method. This PR makes up this deficiency.

2. We have two variants of `fs.write()` / `fs.writeSync()` methods:
   for buffers and strings. Currently, the sync methods have only one
   common reference to the full description of async methods.
   However, the link may seem to belong to the last sync variant only
   (for strings) and, as it refers to the first async variant
   (for buffers), this may be confusing. This PR makes two different
   sync variants refer to two different async variants.

3. In passing, both returned values of sync methods were also made
   more concise and unambiguous.

PR-URL: nodejs#22402
Refs: https://github.com/nodejs/node/blob/a04f2f7df630427bf869b1e04040975b752973b6/lib/fs.js#L549
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
  • Loading branch information
vsemozhetbyt committed Aug 19, 2018
1 parent 14e6274 commit 7108893
Showing 1 changed file with 9 additions and 7 deletions.
16 changes: 9 additions & 7 deletions doc/api/fs.md
Original file line number Diff line number Diff line change
Expand Up @@ -3422,7 +3422,7 @@ changes:
* `fd` {integer}
* `string` {string}
* `position` {integer}
* `encoding` {string}
* `encoding` {string} **Default:** `'utf8'`
* `callback` {Function}
* `err` {Error}
* `written` {integer}
Expand Down Expand Up @@ -3548,7 +3548,10 @@ changes:
* `offset` {integer}
* `length` {integer}
* `position` {integer}
* Returns: {number}
* Returns: {number} The number of bytes written.

For detailed information, see the documentation of the asynchronous version of
this API: [`fs.write(fd, buffer...)`][].

## fs.writeSync(fd, string[, position[, encoding]])
<!-- YAML
Expand All @@ -3563,12 +3566,10 @@ changes:
* `string` {string}
* `position` {integer}
* `encoding` {string}
* Returns: {number}

Returns the number of bytes written.
* Returns: {number} The number of bytes written.

For detailed information, see the documentation of the asynchronous version of
this API: [`fs.write()`][].
this API: [`fs.write(fd, string...)`][].

## fs Promises API

Expand Down Expand Up @@ -4757,7 +4758,8 @@ the file contents.
[`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
[`fs.write(fd, buffer...)`]: #fs_fs_write_fd_buffer_offset_length_position_callback
[`fs.write(fd, string...)`]: #fs_fs_write_fd_string_position_encoding_callback
[`fs.writeFile()`]: #fs_fs_writefile_file_data_options_callback
[`inotify(7)`]: http://man7.org/linux/man-pages/man7/inotify.7.html
[`kqueue(2)`]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
Expand Down

0 comments on commit 7108893

Please sign in to comment.