doc: some fs doc improvements by jasnell · Pull Request #17692 · nodejs/node

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

-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

+* 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

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


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

+
+* 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

+
+* 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

+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

+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

+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

+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

+object.

-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

 description: Added times as numbers.
 -->

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


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

+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

 `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


+*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

 [`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


		* 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.

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

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

Uh oh!

Uh oh!

Conversation

jasnell commented Dec 15, 2017

Checklist

Affected core subsystem(s)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vsemozhetbytDec 15, 2017• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vsemozhetbytDec 15, 2017• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jasnell commented Dec 18, 2017

Uh oh!

jasnell commented Dec 18, 2017

Uh oh!

MylesBorins commented Jan 23, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

vsemozhetbytDec 15, 2017•
edited
Loading

vsemozhetbytDec 15, 2017•
edited
Loading