doc: improve fs doc intro by jasnell · Pull Request #34843 · nodejs/node

jasnell · 2020-08-19T19:59:53Z

Checklist

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

mscdex · 2020-08-20T13:10:01Z

I think the comparison between "asynchronous" and Promise-based APIs could be confusing. The Promise-based APIs definitely are asynchronous, they're just not the callback-based API.

jasnell · 2020-08-20T21:26:44Z

@mscdex updated to address your concern

Trott · 2020-08-21T22:31:44Z

Not blocking on it, but I'm 👎 on the capitalization in Promise-based. The only justification I can think of is that it emphasizes the underlying Promise class. I think that draws attention to the wrong thing (implementation detail) in promise-based.

For what it's worth, MDN agrees, based on the contents of https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Promises (where promise-based appears 7 times and Promise-based not at all).

I also interpret the Microsoft style guide section on capitalization as falling on the "when in doubt, don't capitalize" side of things.

Trott · 2020-08-23T11:12:05Z

I removed the author ready label in light of lpinca's comment and my comment, but I think this is ready to land. I don't think either of those comments are blocking (I know mine isn't and they approved the PR despite the comment they left suggesting a chance.)

Signed-off-by: James M Snell <jasnell@gmail.com>

github-actions · 2020-08-24T17:54:01Z

Commit Queue failed

- Loading data for nodejs/node/pull/34843
✔ Done loading data for nodejs/node/pull/34843
----------------------------------- PR info ------------------------------------
Title doc: improve fs doc intro (#34843)
Author James M Snell (@jasnell)
Branch jasnell:new-fs-doc-improvements -> nodejs:master
Labels author ready, doc, fs
Commits 1
- doc: improve fs doc intro
Committers 1
- James M Snell PR-URL: https://github.com/nodejs/node/pull/34843
Reviewed-By: Anna Henningsen Reviewed-By: Ricky Zhou <0x19951125@gmail.com>
Reviewed-By: Anto Aravinth Reviewed-By: Luigi Pinca ------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/34843
Reviewed-By: Anna Henningsen Reviewed-By: Ricky Zhou <0x19951125@gmail.com>
Reviewed-By: Anto Aravinth Reviewed-By: Luigi Pinca --------------------------------------------------------------------------------
⚠ Commits were pushed since the last review:
⚠ - doc: improve fs doc intro
✖ No CI runs detected
ℹ This PR was created on Wed, 19 Aug 2020 19:59:53 GMT
✔ Approvals: 4
✔ - Anna Henningsen (@addaleax): https://github.com/nodejs/node/pull/34843#pullrequestreview-470845622
✔ - Ricky Zhou (@rickyes): https://github.com/nodejs/node/pull/34843#pullrequestreview-471545184
✔ - Anto Aravinth (@antsmartian): https://github.com/nodejs/node/pull/34843#pullrequestreview-472057857
✔ - Luigi Pinca (@lpinca): https://github.com/nodejs/node/pull/34843#pullrequestreview-472762285
--------------------------------------------------------------------------------
✔ Aborted `git node land` session in /home/runner/work/node/node/.ncu

jasnell · 2020-08-24T18:07:51Z

Landed in 010383a

Signed-off-by: James M Snell <jasnell@gmail.com> PR-URL: #34843 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Ricky Zhou <0x19951125@gmail.com> Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>

nodejs#34843 was cherry-picked onto `v12.x-staging` in 961844d but the `fs/promises` API, as used in the examples, is only available from Node.js 14. Change the added examples to use `require(fs).promises` instead.

#34843 was cherry-picked onto `v12.x-staging` in 961844d but the `fs/promises` API, as used in the examples, is only available from Node.js 14. Change the added examples to use `require(fs).promises` instead. PR-URL: #35760Fixes: #35740 Refs: #34843 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com> Reviewed-By: Ricky Zhou <0x19951125@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com>

nodejs-github-bot added doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system. labels Aug 19, 2020

addaleax approved these changes Aug 19, 2020
View reviewed changes