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: small fixes in the buffer.md #9795

Closed
wants to merge 10 commits into from
Closed

doc: small fixes in the buffer.md #9795

wants to merge 10 commits into from

Conversation

vsemozhetbyt
Copy link
Contributor

@vsemozhetbyt vsemozhetbyt commented Nov 25, 2016

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

doc, buffer

Description of change
  1. var => const / let.
  2. Fix a syntax error.
  3. Fix wrong arguments in function calls*.
  4. Fix some copy-paste artifacts.
  5. Repeat the remark about buffer module property where it is needed.
  6. Add a missing variable declaration.
  7. Remove / fix wrong remarks in the buffer.md
  8. Fix examples in buffer.md to avoid confusion (fixes Some questions about buffer doc #9786)
  9. Remove an extraneous word in the buffer.md

*As to null => undefined in point 3, it is a temporary fix untill #9801 is addressed.

@nodejs-github-bot nodejs-github-bot added buffer Issues and PRs related to the buffer subsystem. doc Issues and PRs related to the documentations. labels Nov 25, 2016
@@ -404,14 +404,14 @@ to initialize a `Buffer` to zeroes.
Example:

```js
const buf = new Buffer(5);
const buf = new Buffer(10);
Copy link
Contributor

Choose a reason for hiding this comment

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

how is this a fix? why is 10 better than 5?

Copy link
Contributor Author

@vsemozhetbyt vsemozhetbyt Nov 25, 2016

Choose a reason for hiding this comment

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

See #9786. This increases the example size (with the predicted outputs in the comments) so the output could not be confusing if the example is testing via a file.

Copy link
Contributor

Choose a reason for hiding this comment

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

Scanned #9876, not finding what you mean. And further confused by "testing via a file". There is no file in this example. PR should standalone, can you describe why this is an improvement?

Copy link
Contributor Author

@vsemozhetbyt vsemozhetbyt Nov 25, 2016

Choose a reason for hiding this comment

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

Sorry for my incomprehensibility. Consider this case: a user copies this example, pastes it in the empty file test.js, saves it and runs via console or IDE to see the output. He will not see the described output, he will see two identical lines with null bytes all the times. In #9786 I've described the cause. This fix increases the size of possible test.js so the two lines will be different. I'll try to make some GIFs now to explain more clearly what I mean.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

In the first GIF you can see a test attempt with the old code example. See how both output lines are the same in contravention of the doc prediction.

buffer1

In the second GIF you can see a test attempt with the new code example. See how both output lines are different as the doc predicts.

buffer2

Copy link
Contributor

Choose a reason for hiding this comment

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

I guess I don't mind the buffer getting a bit bigger, but if you are hoping that means it will always be non-zero.... I don't think that's true. Your own system proves that the initial values can be anything, right? 10 bytes is not special, AFAICT.

Copy link
Contributor

Choose a reason for hiding this comment

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

Thus I think the docs should make the behaviour clear, not the examples. Examples show only one scenario, the docs say how it will be for all scenarios. And frankly, I don't get the point of this example, it doesn't add anything to my understanding. The docs already said the memory wouldn't be initialized. But that's another issue, I guess.

Copy link
Contributor Author

@vsemozhetbyt vsemozhetbyt Nov 25, 2016

Choose a reason for hiding this comment

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

"Contents may vary" does mean it can be anything, including zeroed, but in my case, it is always all zeroes. I do not mean it is true for all the systems, but my case shows that for some systems it is. If the output is all zeroes one time and is not all zeroes another time, it would be OK. But persistent zeroes is confusing, it can make a novice think that doc is wrong.

In the #9786 I've linked to stats that show my system not always zero buffers 8 bytes or smaller. It has some correlation between script size and buffer zeroing scheme. Maybe I have a unique situation. But it seems we won't get more stats because I can't make my point clear(

So what should I do? Just not change these fragments?

Copy link
Contributor

Choose a reason for hiding this comment

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

I don't know. It clearly confused you, and docs should clarify, not confuse. On the other hand, 10 seems as random as 5. I guess leave it, at least anyone wondering why it was changed can find the PR, this conversation, and understand why it changed.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Thank you for the patience.

So can I remake the PR as I've described below?

@@ -523,14 +523,14 @@ initialized*. The contents of the newly created `Buffer` are unknown and
Example:

```js
const buf = Buffer.allocUnsafe(5);
const buf = Buffer.allocUnsafe(10);
Copy link
Contributor

Choose a reason for hiding this comment

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

ditto

@@ -1264,7 +1264,7 @@ console.log(buf.lastIndexOf('buffer', 4));
const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'ucs2');

// Prints: 6
console.log(utf16Buffer.lastIndexOf('\u03a3', null, 'ucs2'));
console.log(utf16Buffer.lastIndexOf('\u03a3', buf.length, 'ucs2'));
Copy link
Contributor

Choose a reason for hiding this comment

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

null didn't work? It looks like the example was trying to show how the second argument has a sensible default, and you have just provided the default value explicitly.

Copy link
Contributor Author

@vsemozhetbyt vsemozhetbyt Nov 25, 2016

Choose a reason for hiding this comment

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

With null it outputs -1. See https://github.com/nodejs/node/blob/master/lib/buffer.js#L601 — it seems null is converted to 0 here, so null is not a replacement for default value or argument omission.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

However, I am not so sure about this now. It seems the doc is right, but the lib code is wrong. See https://github.com/nodejs/node/blob/master/lib/buffer.js#L603. Maybe we should fix the lib instead.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I've created an issue concerning this.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Maybe null could be changed into undefined for now (undefined does print 6 here). And if #9801 is fixed, we could restore the null .

Copy link
Contributor

@sam-github sam-github left a comment

Choose a reason for hiding this comment

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

I'd prefer that this be broken into seperate commits, doc: small fixes in the buffer.md is an uninformative commit message. The bullet list in the commit body that lists unrelated changes is a sign that it should have been multiple commits in a single PR, and the bullet list that just refers to a github issue isn't helpful, the commit message should stand alone, though linking to an issue for further information can be helpful. In this case, the PR will land with the commits amended to point to the PR, so it would be better to mention the issue in the PR, not the commit message.

@vsemozhetbyt
Copy link
Contributor Author

vsemozhetbyt commented Nov 25, 2016

@sam-github Well, I could try, but I am a bit confused how to do this. If I just add several commits to the branch (with undoing most changes in the first new one), will not the first obsolete commit remain in the history? Sorry, I am not a git pro, I usually use GitHub interface(

@vsemozhetbyt
Copy link
Contributor Author

vsemozhetbyt commented Nov 25, 2016

I've tried to understand the git commands for this case. Can I do git commit --amend --all and git push --force-with-lease in my branch to re-commit this big commit into a smaller one in a row, and then just add some new small commits? Will it be safe for this PR and the upstream history?

@vsemozhetbyt
Copy link
Contributor Author

So maybe I'll try it now. If this causes a mess, I'll just close the PR and recreate it with a link to this conversation.

@vsemozhetbyt
Copy link
Contributor Author

@sam-github Does it seem OK now?

@@ -2306,6 +2306,9 @@ added: v3.0.0
On 32-bit architectures, this value is `(2^30)-1` (~1GB).
On 64-bit architectures, this value is `(2^31)-1` (~2GB).

Note that this is a property on the `buffer` module as returned by
Copy link
Contributor

Choose a reason for hiding this comment

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

the word "as" is extraneous

@sam-github
Copy link
Contributor

doc: fix examples in buffer.md to avoid confusion, the commit message is confusing, because its not obvious what is confusing about 5, that 10 fixes. The message body should say something like "On some systems, small buffer allocations can be zeroed by default, so the example doesn't work well - the buffer looks zeroed even before the fill."

On some systems, some first bytes of allocated buffer can be zeroed
by default, so the example doesn't work well - the buffer looks zeroed
even before the fill.

Fixes #9786
@vsemozhetbyt
Copy link
Contributor Author

@sam-github Should I cc somebody for another review?

@sam-github
Copy link
Contributor

I and a number of folks are at node interactive this week, I'd give it a few days before worrying that you've been forgotten. And I think two reviews are usually wanted, @nodejs/documentation, maybe someone else can review?

@@ -1223,7 +1223,7 @@ added: v6.0.0
-->

* `value` {String | Buffer | Integer} What to search for
* `byteOffset` {Integer} Where to begin searching in `buf` (not inclusive).
* `byteOffset` {Integer} Where to begin searching in `buf`.
**Default:** [`buf.length`]
Copy link
Contributor

Choose a reason for hiding this comment

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

Default is actually buf.length - 1.

byteOffset = dir ? 0 : (buffer.length - 1);

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@silverwind Should I preserve the link? Should it be

[`buf.length - 1`][`buf.length`]

Copy link
Contributor

Choose a reason for hiding this comment

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

Put the - 1 outside the link.

@@ -1264,7 +1264,7 @@ console.log(buf.lastIndexOf('buffer', 4));
const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'ucs2');

// Prints: 6
console.log(utf16Buffer.lastIndexOf('\u03a3', null, 'ucs2'));
console.log(utf16Buffer.lastIndexOf('\u03a3', undefined, 'ucs2'));
Copy link
Contributor

@silverwind silverwind Dec 3, 2016

Choose a reason for hiding this comment

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

Both null and undefined are technically not valid arguments. Maybe make a better example?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@silverwind It is a bit complicated here and I hoped it would be fixed fully when #9801 is addressed. Maybe this could be postponed till that big issue fixed?

Copy link
Contributor

Choose a reason for hiding this comment

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

Yeah fine with me.

@vsemozhetbyt
Copy link
Contributor Author

@sam-github, @silverwind Does it require more reviews to land?

@silverwind
Copy link
Contributor

Not strictly, but I'd like to give it a day or two before landing in case someone else wants to chime in.

jmdarling pushed a commit to jmdarling/node that referenced this pull request Dec 8, 2016
PR-URL: nodejs#9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
jmdarling pushed a commit to jmdarling/node that referenced this pull request Dec 8, 2016
PR-URL: nodejs#9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
jmdarling pushed a commit to jmdarling/node that referenced this pull request Dec 8, 2016
PR-URL: nodejs#9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
jmdarling pushed a commit to jmdarling/node that referenced this pull request Dec 8, 2016
On some systems, some first bytes of allocated buffer can be zeroed
by default, so the example doesn't work well - the buffer looks zeroed
even before the fill.

Fixes: nodejs#9786
PR-URL: nodejs#9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
jmdarling pushed a commit to jmdarling/node that referenced this pull request Dec 8, 2016
PR-URL: nodejs#9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
jmdarling pushed a commit to jmdarling/node that referenced this pull request Dec 8, 2016
PR-URL: nodejs#9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Fishrock123 pushed a commit that referenced this pull request Dec 13, 2016
PR-URL: #9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
@italoacasas italoacasas mentioned this pull request Dec 15, 2016
@MylesBorins
Copy link
Contributor

the number of discrete changes in this PR makes it a bit difficult to backport. Would someone be willing to manually backport

MylesBorins pushed a commit that referenced this pull request Mar 7, 2017
PR-URL: #9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
MylesBorins pushed a commit that referenced this pull request Mar 7, 2017
PR-URL: #9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
MylesBorins pushed a commit that referenced this pull request Mar 7, 2017
PR-URL: #9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
MylesBorins pushed a commit that referenced this pull request Mar 7, 2017
PR-URL: #9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
MylesBorins pushed a commit that referenced this pull request Mar 7, 2017
PR-URL: #9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
MylesBorins pushed a commit that referenced this pull request Mar 7, 2017
On some systems, some first bytes of allocated buffer can be zeroed
by default, so the example doesn't work well - the buffer looks zeroed
even before the fill.

Fixes: #9786
PR-URL: #9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
MylesBorins pushed a commit that referenced this pull request Mar 7, 2017
PR-URL: #9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
MylesBorins pushed a commit that referenced this pull request Mar 9, 2017
PR-URL: #9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
MylesBorins pushed a commit that referenced this pull request Mar 9, 2017
PR-URL: #9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
MylesBorins pushed a commit that referenced this pull request Mar 9, 2017
PR-URL: #9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
MylesBorins pushed a commit that referenced this pull request Mar 9, 2017
PR-URL: #9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
MylesBorins pushed a commit that referenced this pull request Mar 9, 2017
PR-URL: #9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
MylesBorins pushed a commit that referenced this pull request Mar 9, 2017
On some systems, some first bytes of allocated buffer can be zeroed
by default, so the example doesn't work well - the buffer looks zeroed
even before the fill.

Fixes: #9786
PR-URL: #9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
MylesBorins pushed a commit that referenced this pull request Mar 9, 2017
PR-URL: #9795
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
@MylesBorins MylesBorins mentioned this pull request Mar 9, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
buffer Issues and PRs related to the buffer subsystem. doc Issues and PRs related to the documentations.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Some questions about buffer doc
6 participants