GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — doc: improve fs api descriptions by evanlucas · Pull Request #17679 · nodejs/node

Conversation

@evanlucas

@evanlucas evanlucas commented Dec 14, 2017

Copy link
Copy Markdown
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
  • documentation is changed or added
  • commit message follows commit guidelines
Affected core subsystem(s)

doc

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
gibfahn reacted with hooray emoji sindresorhus and jasnell reacted with heart emoji
All reactions
  • 🎉 1 reaction
  • ❤️ 2 reactions
@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 Node.js documentation. fs Issues and PRs related to file-system APIs and the fs module. labels Dec 14, 2017
addaleax
addaleax approved these changes Dec 14, 2017
View reviewed changes
Comment thread doc/api/fs.md Outdated

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

@addaleax addaleax Dec 14, 2017

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

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?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@evanlucas evanlucas Dec 14, 2017

Copy link
Copy Markdown
Contributor Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Probably, yes.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@evanlucas
fixup!: change mode to permissions
d01acf2
cjihrig
cjihrig approved these changes Dec 14, 2017
View reviewed changes
jasnell
jasnell reviewed Dec 14, 2017
View reviewed changes
Comment thread doc/api/fs.md Outdated
* `mode` {integer}

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

@jasnell jasnell Dec 14, 2017 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
evanlucas, Fishrock123, and sindresorhus reacted with thumbs up emoji
All reactions
  • 👍 3 reactions
Fishrock123
Fishrock123 approved these changes Dec 14, 2017
View reviewed changes

@Fishrock123 Fishrock123 left a comment

Copy link
Copy Markdown
Contributor

There was a problem hiding this 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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
lpinca
lpinca approved these changes Dec 15, 2017
View reviewed changes
@evanlucas
fixup!: improve text
c2c6509
maclover7
maclover7 approved these changes Dec 18, 2017
View reviewed changes
@maclover7

maclover7 commented Dec 21, 2017

Copy link
Copy Markdown
Contributor

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
jasnell
jasnell approved these changes Dec 21, 2017
View reviewed changes
@maclover7

maclover7 commented Dec 21, 2017

Copy link
Copy Markdown
Contributor

Landing...
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@maclover7 maclover7 self-assigned this Dec 21, 2017
@maclover7

maclover7 commented Dec 21, 2017

Copy link
Copy Markdown
Contributor

Landed in 35511c8
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@maclover7 maclover7 closed this Dec 21, 2017
@evanlucas

evanlucas commented Jan 4, 2018

Copy link
Copy Markdown
Contributor Author

@maclover7 thanks for landing!
maclover7 reacted with heart emoji
All reactions
  • ❤️ 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@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 <[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
@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 <[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
@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 <[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
v9.4.0 proposal #18069
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 <[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
@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 <[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 gibfahn added land-on-v6.x labels Jan 24, 2018
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 <[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
v6.13.0 proposal #18342
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 <[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
@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 <[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
@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 <[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

Reviewers

@jasnell jasnell jasnell approved these changes
@addaleax addaleax addaleax approved these changes
@lpinca lpinca lpinca approved these changes
@cjihrig cjihrig cjihrig approved these changes
+2 more reviewers
@Fishrock123 Fishrock123 Fishrock123 approved these changes
@maclover7 maclover7 maclover7 approved these changes
Reviewers whose approvals may not affect merge requirements

Uh oh!

There was an error while loading. Please reload this page.

Assignees

@maclover7 maclover7

Labels

doc Issues and PRs related to Node.js documentation. fs Issues and PRs related to file-system APIs and the fs module.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

8 participants

@evanlucas @maclover7 @jasnell @addaleax @Fishrock123 @lpinca @cjihrig @gibfahn
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402520 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.