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.

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

doc: improve fs api descriptions #17679

Closed
wants to merge 3 commits into from
Closed

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

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

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

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.

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

@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
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 <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Jeremiah Senkpiel <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Jon Moss <[email protected]>
Reviewed-By: James M Snell <[email protected]>
@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
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 <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Jeremiah Senkpiel <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Jon Moss <[email protected]>
Reviewed-By: James M Snell <[email protected]>
MylesBorins pushed a commit that referenced this pull request Jan 9, 2018
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 <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Jeremiah Senkpiel <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Jon Moss <[email protected]>
Reviewed-By: James M Snell <[email protected]>
MylesBorins pushed a commit that referenced this pull request Jan 9, 2018
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 <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Jeremiah Senkpiel <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Jon Moss <[email protected]>
Reviewed-By: James M Snell <[email protected]>
@MylesBorins MylesBorins mentioned this pull request Jan 10, 2018
gibfahn pushed a commit that referenced this pull request Jan 24, 2018
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 <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Jeremiah Senkpiel <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Jon Moss <[email protected]>
Reviewed-By: James M Snell <[email protected]>
gibfahn pushed a commit that referenced this pull request Jan 24, 2018
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 <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Jeremiah Senkpiel <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Jon Moss <[email protected]>
Reviewed-By: James M Snell <[email protected]>
gibfahn pushed a commit that referenced this pull request Jan 24, 2018
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 <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Jeremiah Senkpiel <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Jon Moss <[email protected]>
Reviewed-By: James M Snell <[email protected]>
@MylesBorins MylesBorins mentioned this pull request Jan 24, 2018
MylesBorins pushed a commit that referenced this pull request Feb 11, 2018
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 <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Jeremiah Senkpiel <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Jon Moss <[email protected]>
Reviewed-By: James M Snell <[email protected]>
MylesBorins pushed a commit that referenced this pull request Feb 12, 2018
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 <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Jeremiah Senkpiel <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Jon Moss <[email protected]>
Reviewed-By: James M Snell <[email protected]>
MylesBorins pushed a commit that referenced this pull request Feb 13, 2018
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 <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Jeremiah Senkpiel <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Jon Moss <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants