doc: some fs doc improvements #17692

jasnell · 2017-12-15T00:36:09Z

Some improvements

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

fs doc

danbev · 2017-12-15T06:13:19Z

doc/api/fs.md

-following is prone to error:
+Note that there is no guaranteed ordering when using asynchronous methods.
+So the following is prone to error because the `fs.stat()` operation may
+completely before the `fs.rename()` operation.


Should this be completely -> complete instead?

lpinca · 2017-12-15T07:52:09Z

doc/api/fs.md

+* Returns: {boolean}
+
+Returns `true` if the `fs.Stats` object describes a character device.
+### stats.isDirectory()


Nit: can we add a new line before this for consistency?

lpinca · 2017-12-15T07:52:20Z

doc/api/fs.md

+* Returns: {boolean}
+
+Returns `true` if the `fs.Stats` object describes a file system directory.
+### stats.isFIFO()


lpinca · 2017-12-15T07:59:27Z

doc/api/fs.md

+
+* Value: {number}
+
+The timestamp indicating the last time this files status was changed expressed


:%s/files/file

this files -> the file or this file's

lpinca · 2017-12-15T08:00:22Z

doc/api/fs.md

+
+* Value: {Date}
+
+The timestamp indicating the last time this files status was changed.


:%s/files/file

this files -> the file or this file's

vsemozhetbyt · 2017-12-15T19:51:47Z

doc/api/fs.md

+The `fs` module provides an API for interacting with the file system in a
+manner closely modeled around standard POSIX functions.
+
+To use this module, use:


A nit: I am not sure, but are these two use a bit monotonous?

vsemozhetbyt · 2017-12-15T19:58:14Z

doc/api/fs.md

+Most `fs` operations accept filepaths that may be specified in the form of
+a string, a [`Buffer`][], or a [`URL`][] object using the `file:` protocol.
+
+String form paths are interpretted as UTF-8 character sequences identifying


interpretted -> interpreted ?

vsemozhetbyt · 2017-12-15T20:07:37Z

doc/api/fs.md

+Example using an absolute path on POSIX:
+
+```js
+fs.open(Buffer.from('/open/some/file.txt'), (err, fd) => {


Missing flag? ('r'?)

vsemozhetbyt · 2017-12-15T20:17:07Z

doc/api/fs.md

+operations use these file descriptors to identify and track each specific
+file. Windows systems use a different but conceptually similar mechanism for
+tracking resources. To simplify things for users, Node.js abstracts away the
+specific differences between operating sytems and assigns all open files a


sytems -> systems

vsemozhetbyt · 2017-12-15T20:25:38Z

doc/api/fs.md


-The object itself emits these events:
+All `fs.FSWatcher` objects are [`EventEmitter`][]'s that will emit a `'change'`


Missing reference?

vsemozhetbyt · 2017-12-15T20:38:54Z

doc/api/fs.md

@@ -321,20 +401,12 @@ changes:
    description: Added times as numbers.
 -->

+An `fs.Stats` object provides information about a file.


vsemozhetbyt · 2017-12-15T20:40:52Z

doc/api/fs.md

+Returns `true` if the `fs.Stats` object describes a symbolic link.
+
+*Note*: This method is only valid when using [`fs.lstat()`][]
+


A nit: delete the extra new line?

vsemozhetbyt · 2017-12-15T20:56:34Z

doc/api/fs.md

@@ -1715,6 +1936,11 @@ a colon, Node.js will open a file system stream, as described by
 Functions based on `fs.open()` exhibit this behavior as well. eg.
 `fs.writeFile()`, `fs.readFile()`, etc.

+*Note:* On Windows, opening an existing hidden file using the `w` flag (either
+through `fs.open` or `fs.writeFile`) will fail with `EPERM`. Existing hidden


fs.open -> fs.open() ?
fs.writeFile -> fs.writeFile() ?

vsemozhetbyt · 2017-12-15T20:56:59Z

doc/api/fs.md

@@ -1715,6 +1936,11 @@ a colon, Node.js will open a file system stream, as described by
 Functions based on `fs.open()` exhibit this behavior as well. eg.
 `fs.writeFile()`, `fs.readFile()`, etc.

+*Note:* On Windows, opening an existing hidden file using the `w` flag (either
+through `fs.open` or `fs.writeFile`) will fail with `EPERM`. Existing hidden
+files can be opened for writing with the `r+` flag. A call to `fs.ftruncate` can


fs.ftruncate -> fs.ftruncate() ?

vsemozhetbyt · 2017-12-18T18:39:20Z

doc/api/fs.md

@@ -3324,6 +3325,7 @@ The following constants are meant for use with the [`fs.Stats`][] object's
 [`URL`]: url.html#url_the_whatwg_url_api
 [`UV_THREADPOOL_SIZE`]: cli.html#cli_uv_threadpool_size_size
 [`WriteStream`]: #fs_class_fs_writestream
+[`EventEmitter']: events.html


Erroneous single quote instead of backtick?

jasnell · 2017-12-18T19:17:10Z

CI lint: https://ci.nodejs.org/job/node-test-linter/14584/

PR-URL: #17692 Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

jasnell · 2017-12-18T19:33:22Z

Landed in 400e73a

PR-URL: #17692 Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins · 2018-01-23T07:18:22Z

Are these changes applicable to 6.x or 8.x?

doc: some fs doc improvements

c906308

nodejs-github-bot added doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system. labels Dec 15, 2017

danbev approved these changes Dec 15, 2017

View reviewed changes

lpinca approved these changes Dec 15, 2017

View reviewed changes

vsemozhetbyt approved these changes Dec 15, 2017

View reviewed changes

[Squash] Fix nits

6eb7ca4

vsemozhetbyt reviewed Dec 18, 2017

View reviewed changes

[Squash] oops

5a101bc

jasnell added a commit that referenced this pull request Dec 18, 2017

doc: some fs doc improvements

400e73a

PR-URL: #17692 Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

jasnell closed this Dec 18, 2017

MylesBorins pushed a commit that referenced this pull request Jan 8, 2018

doc: some fs doc improvements

e70e083

PR-URL: #17692 Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins pushed a commit that referenced this pull request Jan 9, 2018

doc: some fs doc improvements

861f6ad

PR-URL: #17692 Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

MylesBorins mentioned this pull request Jan 10, 2018

v9.4.0 proposal #18069

Merged

MylesBorins added lts-watch-v6.x labels Jan 23, 2018

MylesBorins added dont-land-on-v8.x and removed lts-watch-v6.x labels May 22, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: some fs doc improvements #17692

doc: some fs doc improvements #17692

jasnell commented Dec 15, 2017

danbev Dec 15, 2017

lpinca Dec 15, 2017

lpinca Dec 15, 2017

lpinca Dec 15, 2017

Trott Dec 15, 2017

lpinca Dec 15, 2017

Trott Dec 15, 2017

vsemozhetbyt Dec 15, 2017 •

edited

Loading

vsemozhetbyt Dec 15, 2017

vsemozhetbyt Dec 15, 2017

vsemozhetbyt Dec 15, 2017

vsemozhetbyt Dec 15, 2017

vsemozhetbyt Dec 15, 2017

vsemozhetbyt Dec 15, 2017 •

edited

Loading

vsemozhetbyt Dec 15, 2017

vsemozhetbyt Dec 15, 2017

vsemozhetbyt Dec 18, 2017

jasnell commented Dec 18, 2017

jasnell commented Dec 18, 2017

MylesBorins commented Jan 23, 2018


		* Value: {number}

		The timestamp indicating the last time this files status was changed expressed


		* Value: {Date}

		The timestamp indicating the last time this files status was changed.


		The object itself emits these events:
		All `fs.FSWatcher` objects are [`EventEmitter`][]'s that will emit a `'change'`

		Returns `true` if the `fs.Stats` object describes a symbolic link.

		Note: This method is only valid when using [`fs.lstat()`][]

doc: some fs doc improvements #17692

doc: some fs doc improvements #17692

Conversation

jasnell commented Dec 15, 2017

Checklist

Affected core subsystem(s)

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt Dec 15, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt Dec 15, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasnell commented Dec 18, 2017

jasnell commented Dec 18, 2017

MylesBorins commented Jan 23, 2018

vsemozhetbyt Dec 15, 2017 •

edited

Loading

vsemozhetbyt Dec 15, 2017 •

edited

Loading