doc: improve fs doc intro #34843

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

doc/api/fs.md

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

doc/api/fs.md

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: #35760 Fixes: #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