Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: improve fs api descriptions #17679

Closed
wants to merge 3 commits into from
Closed

doc: improve fs api descriptions #17679

wants to merge 3 commits into from

Conversation

evanlucas
Copy link
Contributor

This improves the api descriptions for fs.chown, fs.chmod, and fs.mkdir
along with their *Sync counterparts.

I have heard from many people how bad our docs are for people not familiar with some standard POSIX functions.

https://twitter.com/sindresorhus/status/939823222517850112 is just one example. I've also been told this in person on multiple occasions.

I think it is time for us to expand and improve our documentation to make it as useful as possible to all developers.

I know this isn't a large change but I do think it is an improvement over what we currently have.
I'm also open to wording/description suggestions.

Checklist
Affected core subsystem(s)

doc

@evanlucas
doc: improve fs api descriptions
236281c 
This improves the api descriptions for fs.chown, fs.chmod, and fs.mkdir
along with their *Sync counterparts.
@addaleax addaleax added doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system. labels Dec 14, 2017
addaleax
addaleax approved these changes Dec 14, 2017
View reviewed changes
doc/api/fs.md Outdated
@@ -669,8 +669,10 @@ changes:
* `callback` {Function}
* `err` {Error}

Asynchronous chmod(2). No arguments other than a possible exception are given
to the completion callback.
Asynchronously changes the mode of a file. No arguments other than a possible
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe even go for “permissions” instead of “mode”? Is that clearer?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably, yes.

jasnell
jasnell reviewed Dec 14, 2017
View reviewed changes
doc/api/fs.md Outdated
@@ -685,7 +687,9 @@ changes:
* `path` {string|Buffer|URL}
* `mode` {integer}

Synchronous chmod(2). Returns `undefined`.
The synchronous version of [`fs.chmod()`][]. Returns `undefined`.
Copy link
Member

@jasnell jasnell Dec 14, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know it duplicates content, but it would be ideal if this wasn't just a link to something else... e.g. this could be

Synchronously change the permissions of a file or throw if unable to do so.

Likewise for the other *Sync variants.

Fishrock123
Fishrock123 approved these changes Dec 14, 2017
View reviewed changes
Copy link
Contributor

@Fishrock123 Fishrock123 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM with @jasnell's suggestion.

@maclover7
Copy link
Contributor

CI: https://ci.nodejs.org/job/node-test-pull-request-lite/36/

@maclover7
Copy link
Contributor

Landing...

@maclover7 maclover7 self-assigned this Dec 21, 2017
@maclover7
Copy link
Contributor

Landed in 35511c8

@maclover7 maclover7 closed this Dec 21, 2017
maclover7 pushed a commit to maclover7/node that referenced this pull request Dec 21, 2017
@evanlucas @maclover7
doc: improve fs api descriptions
35511c8 
This improves the api descriptions for fs.chown, fs.chmod, and fs.mkdir
along with their *Sync counterparts.

PR-URL: nodejs#17679
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Reviewed-By: James M Snell <jasnell@gmail.com>
@evanlucas
Copy link
Contributor Author

@maclover7 thanks for landing!

@evanlucas evanlucas deleted the fsdoc branch January 4, 2018 11:39
MylesBorins pushed a commit that referenced this pull request Jan 8, 2018
@evanlucas @MylesBorins
doc: improve fs api descriptions
7ec4740 
This improves the api descriptions for fs.chown, fs.chmod, and fs.mkdir
along with their *Sync counterparts.

PR-URL: #17679
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Reviewed-By: James M Snell <jasnell@gmail.com>
MylesBorins pushed a commit that referenced this pull request Jan 9, 2018
@evanlucas @MylesBorins
doc: improve fs api descriptions
541801d 
This improves the api descriptions for fs.chown, fs.chmod, and fs.mkdir
along with their *Sync counterparts.

PR-URL: #17679
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Reviewed-By: James M Snell <jasnell@gmail.com>
MylesBorins pushed a commit that referenced this pull request Jan 9, 2018
@evanlucas @MylesBorins
doc: improve fs api descriptions
b6d2090 
This improves the api descriptions for fs.chown, fs.chmod, and fs.mkdir
along with their *Sync counterparts.

PR-URL: #17679
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Reviewed-By: James M Snell <jasnell@gmail.com>
@MylesBorins MylesBorins mentioned this pull request Jan 10, 2018
Merged
gibfahn pushed a commit that referenced this pull request Jan 24, 2018
@evanlucas @gibfahn
doc: improve fs api descriptions
ac8a75d 
This improves the api descriptions for fs.chown, fs.chmod, and fs.mkdir
along with their *Sync counterparts.

PR-URL: #17679
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Reviewed-By: James M Snell <jasnell@gmail.com>
gibfahn pushed a commit that referenced this pull request Jan 24, 2018
@evanlucas @gibfahn
doc: improve fs api descriptions
5784522 
This improves the api descriptions for fs.chown, fs.chmod, and fs.mkdir
along with their *Sync counterparts.

PR-URL: #17679
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Reviewed-By: James M Snell <jasnell@gmail.com>
gibfahn pushed a commit that referenced this pull request Jan 24, 2018
@evanlucas @gibfahn
doc: improve fs api descriptions
4b6c182 
This improves the api descriptions for fs.chown, fs.chmod, and fs.mkdir
along with their *Sync counterparts.

PR-URL: #17679
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Reviewed-By: James M Snell <jasnell@gmail.com>
@MylesBorins MylesBorins mentioned this pull request Jan 24, 2018
Merged
MylesBorins pushed a commit that referenced this pull request Feb 11, 2018
@evanlucas @MylesBorins
doc: improve fs api descriptions
1a966f1 
This improves the api descriptions for fs.chown, fs.chmod, and fs.mkdir
along with their *Sync counterparts.

PR-URL: #17679
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Reviewed-By: James M Snell <jasnell@gmail.com>
MylesBorins pushed a commit that referenced this pull request Feb 12, 2018
@evanlucas @MylesBorins
doc: improve fs api descriptions
61802bc 
This improves the api descriptions for fs.chown, fs.chmod, and fs.mkdir
along with their *Sync counterparts.

PR-URL: #17679
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Reviewed-By: James M Snell <jasnell@gmail.com>
MylesBorins pushed a commit that referenced this pull request Feb 13, 2018
@evanlucas @MylesBorins
doc: improve fs api descriptions
6816414 
This improves the api descriptions for fs.chown, fs.chmod, and fs.mkdir
along with their *Sync counterparts.

PR-URL: #17679
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Reviewed-By: James M Snell <jasnell@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@jasnell jasnell jasnell approved these changes

@addaleax addaleax addaleax approved these changes

@Fishrock123 Fishrock123 Fishrock123 approved these changes

@lpinca lpinca lpinca approved these changes

@cjihrig cjihrig cjihrig approved these changes

@maclover7 maclover7 maclover7 approved these changes

Assignees

@maclover7 maclover7

Labels
doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
8 participants
@evanlucas @maclover7 @jasnell @addaleax @Fishrock123 @lpinca @cjihrig @gibfahn