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: clarifying variables in fs.write() #9792

Closed
wants to merge 1 commit into from
Closed

doc: clarifying variables in fs.write() #9792

wants to merge 1 commit into from

Conversation

jalafel
Copy link
Contributor

@jalafel jalafel commented Nov 24, 2016 •
edited
Loading

Checklist
  • [x ] documentation is changed or added
  • [ x] commit message follows commit guidelines
Affected core subsystem(s)

doc

Description of change

This commit clarifies variables in the Filesystem docs.
Prior, the documentation for fs.write() had an ambiguous
remark on the parameters of offset and length.

Therefore, this commit makes explicit that the length parameter
in fs.write() is used to denote the number of bytes, which is
a clearer reference for its usage.

Ref: #7868

@nodejs-github-bot nodejs-github-bot added doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system. labels Nov 24, 2016
@Trott
Copy link
Member

Trott commented Nov 25, 2016

The variable names in the doc match those in the implementation in lib/fs.js. If we're going to change variable names in the doc, we probably should change them in the implementation as well.

@sam-github
Copy link
Contributor

sam-github commented Nov 25, 2016 •
edited
Loading

This caused ambiguity in the meaning, wherein length is traditionally used to denote index length of a data structure. Therefore, this commit rewords length to size, which is a clearer reference for its usage.

I have trouble parsing your sentence, what is the "index length of a data structure"?

I see length and size pretty much as synonyms.

Use in node is consistent with Javascript, I believe: https://developer.mozilla.org/en-US/search?q=length&topic=api&topic=css&topic=html&topic=js&topic=apps&topic=webdev shows length is used as we use it, length also seems to be the preffered word in V8. length also seems common in python, size is arguably more common in C (but the last two aren't really relevant to node.js).

I think the length to size rename is code churn that doesn't materially improve the code or docs. It also changes the tags, so breaks any links from other pages in the API docs and guides.

Your other textual changes look good.

EDIT: I moved conversation back to the source issue #7868 (comment)

@jalafel jalafel force-pushed the issue#7868 branch 4 times, most recently from dcad495 to f031f14 Compare November 27, 2016 05:43
@jalafel
doc: clarifying variables in fs.write()
a40734a 
This commit clarifies variables in the Filesystem docs.
Prior, the documentation for fs.write() had an ambiguous
remark on the parameters of offset and length.

Therefore, this commit makes explicit that the length parameter
in fs.write() is used to denote the number of bytes, which is
a clearer reference for its usage.

Ref: nodejs#7868
@jalafel jalafel changed the title doc: clarifying variables in fs.write() and fs.read() doc: clarifying variables in fs.write() Nov 28, 2016
@jalafel jalafel mentioned this pull request Jan 15, 2017
Closed
@italoacasas
Copy link
Contributor

Landed 762f260

italoacasas pushed a commit that referenced this pull request Jan 18, 2017
@jalafel @italoacasas
doc: clarifying variables in fs.write()
762f260 
This commit clarifies variables in the Filesystem docs.
Prior, the documentation for fs.write() had an ambiguous
remark on the parameters of offset and length.

Therefore, this commit makes explicit that the length parameter
in fs.write() is used to denote the number of bytes, which is
a clearer reference for its usage.

PR-URL: #9792
Ref: #7868
Reviewed-By: Sam Roberts <[email protected]>
italoacasas pushed a commit to italoacasas/node that referenced this pull request Jan 18, 2017
@jalafel @italoacasas
doc: clarifying variables in fs.write()
c7b631e 
This commit clarifies variables in the Filesystem docs.
Prior, the documentation for fs.write() had an ambiguous
remark on the parameters of offset and length.

Therefore, this commit makes explicit that the length parameter
in fs.write() is used to denote the number of bytes, which is
a clearer reference for its usage.

PR-URL: nodejs#9792
Ref: nodejs#7868
Reviewed-By: Sam Roberts <[email protected]>
italoacasas pushed a commit to italoacasas/node that referenced this pull request Jan 23, 2017
@jalafel @italoacasas
doc: clarifying variables in fs.write()
788ae24 
This commit clarifies variables in the Filesystem docs.
Prior, the documentation for fs.write() had an ambiguous
remark on the parameters of offset and length.

Therefore, this commit makes explicit that the length parameter
in fs.write() is used to denote the number of bytes, which is
a clearer reference for its usage.

PR-URL: nodejs#9792
Ref: nodejs#7868
Reviewed-By: Sam Roberts <[email protected]>
italoacasas pushed a commit to italoacasas/node that referenced this pull request Jan 24, 2017
@jalafel @italoacasas
doc: clarifying variables in fs.write()
39f7501 
This commit clarifies variables in the Filesystem docs.
Prior, the documentation for fs.write() had an ambiguous
remark on the parameters of offset and length.

Therefore, this commit makes explicit that the length parameter
in fs.write() is used to denote the number of bytes, which is
a clearer reference for its usage.

PR-URL: nodejs#9792
Ref: nodejs#7868
Reviewed-By: Sam Roberts <[email protected]>
@italoacasas italoacasas mentioned this pull request Jan 25, 2017
Closed
italoacasas pushed a commit to italoacasas/node that referenced this pull request Jan 27, 2017
@jalafel @italoacasas
doc: clarifying variables in fs.write()
520b1f7 
This commit clarifies variables in the Filesystem docs.
Prior, the documentation for fs.write() had an ambiguous
remark on the parameters of offset and length.

Therefore, this commit makes explicit that the length parameter
in fs.write() is used to denote the number of bytes, which is
a clearer reference for its usage.

PR-URL: nodejs#9792
Ref: nodejs#7868
Reviewed-By: Sam Roberts <[email protected]>
@italoacasas italoacasas mentioned this pull request Jan 29, 2017
Merged
MylesBorins pushed a commit that referenced this pull request Mar 7, 2017
@jalafel @MylesBorins
doc: clarifying variables in fs.write()
9b39973 
This commit clarifies variables in the Filesystem docs.
Prior, the documentation for fs.write() had an ambiguous
remark on the parameters of offset and length.

Therefore, this commit makes explicit that the length parameter
in fs.write() is used to denote the number of bytes, which is
a clearer reference for its usage.

PR-URL: #9792
Ref: #7868
Reviewed-By: Sam Roberts <[email protected]>
MylesBorins pushed a commit that referenced this pull request Mar 7, 2017
@jalafel @MylesBorins
doc: clarifying variables in fs.write()
3272eec 
This commit clarifies variables in the Filesystem docs.
Prior, the documentation for fs.write() had an ambiguous
remark on the parameters of offset and length.

Therefore, this commit makes explicit that the length parameter
in fs.write() is used to denote the number of bytes, which is
a clearer reference for its usage.

PR-URL: #9792
Ref: #7868
Reviewed-By: Sam Roberts <[email protected]>
MylesBorins pushed a commit that referenced this pull request Mar 9, 2017
@jalafel @MylesBorins
doc: clarifying variables in fs.write()
787d4ec 
This commit clarifies variables in the Filesystem docs.
Prior, the documentation for fs.write() had an ambiguous
remark on the parameters of offset and length.

Therefore, this commit makes explicit that the length parameter
in fs.write() is used to denote the number of bytes, which is
a clearer reference for its usage.

PR-URL: #9792
Ref: #7868
Reviewed-By: Sam Roberts <[email protected]>
@MylesBorins MylesBorins mentioned this pull request Mar 9, 2017
Merged
MylesBorins pushed a commit that referenced this pull request Mar 9, 2017
@jalafel @MylesBorins
doc: clarifying variables in fs.write()
6d0e162 
This commit clarifies variables in the Filesystem docs.
Prior, the documentation for fs.write() had an ambiguous
remark on the parameters of offset and length.

Therefore, this commit makes explicit that the length parameter
in fs.write() is used to denote the number of bytes, which is
a clearer reference for its usage.

PR-URL: #9792
Ref: #7868
Reviewed-By: Sam Roberts <[email protected]>
@MylesBorins MylesBorins mentioned this pull request Mar 9, 2017
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@sam-github sam-github sam-github approved these changes

Assignees
No one assigned
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.
6 participants
@jalafel @Trott @sam-github @italoacasas @MylesBorins @nodejs-github-bot