Commit c17e980
doc: clarify fs.write[Sync]() descriptions
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: #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>1 parent 1ebaa2a commit c17e980
1 file changed
Lines changed: 9 additions & 7 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -3402,7 +3402,7 @@ changes: | |||
| 3402 | 3402 | * `fd` {integer} | |
| 3403 | 3403 | * `string` {string} | |
| 3404 | 3404 | * `position` {integer} | |
| 3405 | - * `encoding` {string} | ||
| 3405 | + * `encoding` {string} **Default:** `'utf8'` | ||
| 3406 | 3406 | * `callback` {Function} | |
| 3407 | 3407 | * `err` {Error} | |
| 3408 | 3408 | * `written` {integer} | |
@@ -3528,7 +3528,10 @@ changes: | |||
| 3528 | 3528 | * `offset` {integer} | |
| 3529 | 3529 | * `length` {integer} | |
| 3530 | 3530 | * `position` {integer} | |
| 3531 | - * Returns: {number} | ||
| 3531 | + * Returns: {number} The number of bytes written. | ||
| 3532 | + | ||
| 3533 | + For detailed information, see the documentation of the asynchronous version of | ||
| 3534 | + this API: [`fs.write(fd, buffer...)`][]. | ||
| 3532 | 3535 | ||
| 3533 | 3536 | ## fs.writeSync(fd, string[, position[, encoding]]) | |
| 3534 | 3537 | <!-- YAML | |
@@ -3543,12 +3546,10 @@ changes: | |||
| 3543 | 3546 | * `string` {string} | |
| 3544 | 3547 | * `position` {integer} | |
| 3545 | 3548 | * `encoding` {string} | |
| 3546 | - * Returns: {number} | ||
| 3547 | - | ||
| 3548 | - Returns the number of bytes written. | ||
| 3549 | + * Returns: {number} The number of bytes written. | ||
| 3549 | 3550 | ||
| 3550 | 3551 | For detailed information, see the documentation of the asynchronous version of | |
| 3551 | - this API: [`fs.write()`][]. | ||
| 3552 | + this API: [`fs.write(fd, string...)`][]. | ||
| 3552 | 3553 | ||
| 3553 | 3554 | ## fs Promises API | |
| 3554 | 3555 | ||
@@ -4731,7 +4732,8 @@ the file contents. | |||
| 4731 | 4732 | [`fs.symlink()`]: #fs_fs_symlink_target_path_type_callback | |
| 4732 | 4733 | [`fs.utimes()`]: #fs_fs_utimes_path_atime_mtime_callback | |
| 4733 | 4734 | [`fs.watch()`]: #fs_fs_watch_filename_options_listener | |
| 4734 | - [`fs.write()`]: #fs_fs_write_fd_buffer_offset_length_position_callback | ||
| 4735 | + [`fs.write(fd, buffer...)`]: #fs_fs_write_fd_buffer_offset_length_position_callback | ||
| 4736 | + [`fs.write(fd, string...)`]: #fs_fs_write_fd_string_position_encoding_callback | ||
| 4735 | 4737 | [`fs.writeFile()`]: #fs_fs_writefile_file_data_options_callback | |
| 4736 | 4738 | [`inotify(7)`]: http://man7.org/linux/man-pages/man7/inotify.7.html | |
| 4737 | 4739 | [`kqueue(2)`]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 | |
0 commit comments