diff options
author | Rich Trott <rtrott@gmail.com> | 2018-07-03 16:51:28 -0700 |
---|---|---|
committer | Rich Trott <rtrott@gmail.com> | 2018-07-05 21:36:21 -0700 |
commit | f545ae9589f97de0f403b61b5b3075bbb527309b (patch) | |
tree | 8c88bd7042dbfb0e01e660a029748b04c866a1d4 /doc | |
parent | e55bdde92513ecf4915390c772f5ffa5da2c9f5e (diff) | |
download | android-node-v8-f545ae9589f97de0f403b61b5b3075bbb527309b.tar.gz android-node-v8-f545ae9589f97de0f403b61b5b3075bbb527309b.tar.bz2 android-node-v8-f545ae9589f97de0f403b61b5b3075bbb527309b.zip |
doc: remove "note that" from fs doc
Remove "note that" from the fs documentation, along with other minor
nearby improvements.
Before:
Note that some characters are obscured by Strong Bad's head.
After:
Some characters are obscured by Strong Bad's head.
PR-URL: https://github.com/nodejs/node/pull/21646
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/fs.md | 118 |
1 files changed, 56 insertions, 62 deletions
diff --git a/doc/api/fs.md b/doc/api/fs.md index e33acafb97..aa1a43f1ec 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -45,9 +45,9 @@ try { } ``` -Note that there is no guaranteed ordering when using asynchronous methods. -So the following is prone to error because the `fs.stat()` operation may -complete before the `fs.rename()` operation. +There is no guaranteed ordering when using asynchronous methods. So the +following is prone to error because the `fs.stat()` operation may complete +before the `fs.rename()` operation: ```js fs.rename('/tmp/hello', '/tmp/world', (err) => { @@ -150,8 +150,8 @@ fs.open(Buffer.from('/open/some/file.txt'), 'r', (err, fd) => { }); ``` -*Note:* On Windows Node.js follows the concept of per-drive working directory. -This behavior can be observed when using a drive path without a backslash. For +On Windows, Node.js follows the concept of per-drive working directory. This +behavior can be observed when using a drive path without a backslash. For example `fs.readdirSync('c:\\')` can potentially return a different result than `fs.readdirSync('c:')`. For more information, see [this MSDN page][MSDN-Rel-Path]. @@ -278,9 +278,9 @@ eventually cause an application to crash. ## Threadpool Usage -Note that all file system APIs except `fs.FSWatcher()` and those that are -explicitly synchronous use libuv's threadpool, which can have surprising and -negative performance implications for some applications, see the +All file system APIs except `fs.FSWatcher()` and those that are explicitly +synchronous use libuv's threadpool, which can have surprising and negative +performance implications for some applications. See the [`UV_THREADPOOL_SIZE`][] documentation for more information. ## Class: fs.FSWatcher @@ -689,15 +689,13 @@ The times in the stat object have the following semantics: * `birthtime` "Birth Time" - Time of file creation. Set once when the file is created. On filesystems where birthtime is not available, this field may instead hold either the `ctime` or - `1970-01-01T00:00Z` (ie, unix epoch timestamp `0`). Note that this - value may be greater than `atime` or `mtime` in this case. On Darwin - and other FreeBSD variants, also set if the `atime` is explicitly - set to an earlier value than the current `birthtime` using the - utimes(2) system call. + `1970-01-01T00:00Z` (ie, unix epoch timestamp `0`). This value may be greater + than `atime` or `mtime` in this case. On Darwin and other FreeBSD variants, + also set if the `atime` is explicitly set to an earlier value than the current + `birthtime` using the utimes(2) system call. -Prior to Node.js v0.12, the `ctime` held the `birthtime` on Windows -systems. Note that as of v0.12, `ctime` is not "creation time", and -on Unix systems, it never was. +Prior to Node.js 0.12, the `ctime` held the `birthtime` on Windows systems. As +of 0.12, `ctime` is not "creation time", and on Unix systems, it never was. ## Class: fs.WriteStream <!-- YAML @@ -1117,11 +1115,10 @@ For example, the octal value `0o765` means: * The group may read and write the file. * Others may read and execute the file. -Note: When using raw numbers where file modes are expected, -any value larger than `0o777` may result in platform-specific -behaviors that are not supported to work consistently. -Therefore constants like `S_ISVTX`, `S_ISGID` or `S_ISUID` are -not exposed in `fs.constants`. +When using raw numbers where file modes are expected, any value larger than +`0o777` may result in platform-specific behaviors that are not supported to work +consistently. Therefore constants like `S_ISVTX`, `S_ISGID` or `S_ISUID` are not +exposed in `fs.constants`. Caveats: on Windows only the write permission can be changed, and the distinction among the permissions of group, owner or others is not @@ -1378,8 +1375,8 @@ The `encoding` can be any one of those accepted by [`Buffer`][]. If `fd` is specified, `ReadStream` will ignore the `path` argument and will use the specified file descriptor. This means that no `'open'` event will be -emitted. Note that `fd` should be blocking; non-blocking `fd`s should be passed -to [`net.Socket`][]. +emitted. `fd` should be blocking; non-blocking `fd`s should be passed to +[`net.Socket`][]. If `autoClose` is false, then the file descriptor won't be closed, even if there's an error. It is the application's responsibility to close it and make @@ -1442,8 +1439,8 @@ file descriptor leak. Like [`ReadStream`][], if `fd` is specified, [`WriteStream`][] will ignore the `path` argument and will use the specified file descriptor. This means that no -`'open'` event will be emitted. Note that `fd` should be blocking; non-blocking -`fd`s should be passed to [`net.Socket`][]. +`'open'` event will be emitted. `fd` should be blocking; non-blocking `fd`s +should be passed to [`net.Socket`][]. If `options` is a string, then it specifies the encoding. @@ -1473,11 +1470,11 @@ fs.exists('/etc/passwd', (exists) => { }); ``` -**Note that the parameter to this callback is not consistent with other -Node.js callbacks.** Normally, the first parameter to a Node.js callback is -an `err` parameter, optionally followed by other parameters. The -`fs.exists()` callback has only one boolean parameter. This is one reason -`fs.access()` is recommended instead of `fs.exists()`. +**The parameters for this callback are not consistent with other Node.js +callbacks.** Normally, the first parameter to a Node.js callback is an `err` +parameter, optionally followed by other parameters. The `fs.exists()` callback +has only one boolean parameter. This is one reason `fs.access()` is recommended +instead of `fs.exists()`. Using `fs.exists()` to check for the existence of a file before calling `fs.open()`, `fs.readFile()` or `fs.writeFile()` is not recommended. Doing @@ -1573,10 +1570,9 @@ changes: Synchronous version of [`fs.exists()`][]. Returns `true` if the path exists, `false` otherwise. -Note that `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.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 @@ -2149,9 +2145,8 @@ fs.mkdtemp(tmpDir, (err, folder) => { if (err) throw err; console.log(folder); // Will print something similar to `/tmpabc123`. - // Note that a new temporary directory is created - // at the file system root rather than *within* - // the /tmp directory. + // A new temporary directory is created at the file system root + // rather than *within* the /tmp directory. }); // This method is *CORRECT*: @@ -2204,8 +2199,8 @@ changes: Asynchronous file open. See open(2). `mode` sets the file mode (permission and sticky bits), but only if the file was -created. Note that on Windows only the write permission can be manipulated, -see [`fs.chmod()`][]. +created. On Windows, only the write permission can be manipulated; see +[`fs.chmod()`][]. The callback gets two arguments `(err, fd)`. @@ -2843,9 +2838,9 @@ changes: Asynchronous symlink(2). No arguments other than a possible exception are given to the completion callback. The `type` argument can be set to `'dir'`, `'file'`, or `'junction'` and is only available on -Windows (ignored on other platforms). Note that Windows junction points require -the destination path to be absolute. When using `'junction'`, the `target` -argument will automatically be normalized to absolute path. +Windows (ignored on other platforms). Windows junction points require the +destination path to be absolute. When using `'junction'`, the `target` argument +will automatically be normalized to absolute path. Here is an example below: @@ -3086,10 +3081,10 @@ The listener callback gets two arguments `(eventType, filename)`. `eventType` is either `'rename'` or `'change'`, and `filename` is the name of the file which triggered the event. -Note that on most platforms, `'rename'` is emitted whenever a filename appears -or disappears in the directory. +On most platforms, `'rename'` is emitted whenever a filename appears or +disappears in the directory. -Also note the listener callback is attached to the `'change'` event fired by +The listener callback is attached to the `'change'` event fired by [`fs.FSWatcher`][], but it is not the same thing as the `'change'` value of `eventType`. @@ -3266,9 +3261,8 @@ The callback will be given three arguments `(err, bytesWritten, buffer)` where If this method is invoked as its [`util.promisify()`][]ed version, it returns a `Promise` for an `Object` with `bytesWritten` and `buffer` properties. -Note that it is unsafe to use `fs.write` multiple times on the same file -without waiting for the callback. For this scenario, -`fs.createWriteStream` is strongly recommended. +It is unsafe to use `fs.write()` multiple times on the same file without waiting +for the callback. For this scenario, `fs.createWriteStream()` is recommended. On Linux, positional writes don't work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to @@ -3310,12 +3304,12 @@ the current position. See pwrite(2). `encoding` is the expected string encoding. The callback will receive the arguments `(err, written, string)` where `written` -specifies how many _bytes_ the passed string required to be written. Note that -bytes written is not the same as string characters. See [`Buffer.byteLength`][]. +specifies how many _bytes_ the passed string required to be written. Bytes +written is not necessarily the same as string characters written. See +[`Buffer.byteLength`][]. -Note that it is unsafe to use `fs.write` multiple times on the same file -without waiting for the callback. For this scenario, -`fs.createWriteStream` is strongly recommended. +It is unsafe to use `fs.write()` multiple times on the same file without waiting +for the callback. For this scenario, `fs.createWriteStream()` is recommended. On Linux, positional writes don't work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to @@ -3372,9 +3366,9 @@ fs.writeFile('message.txt', 'Hello Node.js', 'utf8', callback); Any specified file descriptor has to support writing. -Note that it is unsafe to use `fs.writeFile` multiple times on the same file -without waiting for the callback. For this scenario, -`fs.createWriteStream` is strongly recommended. +It is unsafe to use `fs.writeFile()` multiple times on the same file without +waiting for the callback. For this scenario, `fs.createWriteStream()` is +recommended. If a file descriptor is specified as the `file`, it will not be closed automatically. @@ -4161,9 +4155,9 @@ Creates a symbolic link then resolves the `Promise` with no arguments upon success. The `type` argument is only used on Windows platforms and can be one of `'dir'`, -`'file'`, or `'junction'`. Note that Windows junction -points require the destination path to be absolute. When using `'junction'`, -the `target` argument will automatically be normalized to absolute path. +`'file'`, or `'junction'`. Windows junction points require the destination path +to be absolute. When using `'junction'`, the `target` argument will +automatically be normalized to absolute path. ### fsPromises.truncate(path[, len]) <!-- YAML @@ -4525,9 +4519,9 @@ string: skipping the potentially stale local cache. It has a very real impact on I/O performance so using this flag is not recommended unless it is needed. - Note that this doesn't turn `fs.open()` or `fsPromises.open()` into a - synchronous blocking call. If synchronous operation is desired, something - like `fs.openSync()` should be used. + This doesn't turn `fs.open()` or `fsPromises.open()` into a synchronous + blocking call. If synchronous operation is desired, something like + `fs.openSync()` should be used. * `'w'` - Open file for writing. The file is created (if it does not exist) or truncated (if it exists). |