doc: small fixes in the buffer.md #9795

vsemozhetbyt · 2016-11-25T04:16:54Z

Checklist

documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc, buffer

Description of change

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

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

sam-github · 2016-11-25T16:06:24Z

doc/api/buffer.md

@@ -404,14 +404,14 @@ to initialize a `Buffer` to zeroes.
 Example:

 ```js
-const buf = new Buffer(5);
+const buf = new Buffer(10);


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

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.

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?

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.

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.

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.

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.

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.

"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?

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.

Thank you for the patience.

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

sam-github · 2016-11-25T16:06:34Z

doc/api/buffer.md

@@ -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);


sam-github · 2016-11-25T16:08:06Z

doc/api/buffer.md

@@ -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'));


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.

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.

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.

It becomes more weird: https://github.com/nodejs/node/blob/master/test/parallel/test-buffer-indexof.js#L407

I've created an issue concerning this.

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

sam-github

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 · 2016-11-25T19:58:02Z

@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 · 2016-11-25T22:14:55Z

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 · 2016-11-26T20:42:00Z

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 · 2016-11-27T17:34:16Z

@sam-github Does it seem OK now?

sam-github · 2016-11-27T22:19:22Z

doc/api/buffer.md

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


the word "as" is extraneous

sam-github · 2016-11-27T22:22:58Z

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 · 2016-11-30T04:06:59Z

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

sam-github · 2016-11-30T21:52:05Z

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?

silverwind · 2016-12-03T14:10:51Z

doc/api/buffer.md

@@ -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`]


Default is actually buf.length - 1.

node/lib/buffer.js

Line 594 in e21e129

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

@silverwind Should I preserve the link? Should it be

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

Put the - 1 outside the link.

silverwind · 2016-12-03T14:12:57Z

doc/api/buffer.md

@@ -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'));


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

@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?

Yeah fine with me.

vsemozhetbyt · 2016-12-04T12:22:47Z

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

silverwind · 2016-12-04T12:25:52Z

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

PR-URL: nodejs#9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

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 <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

PR-URL: nodejs#9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

MylesBorins · 2016-12-20T20:53:53Z

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

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

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 <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

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 <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

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

sam-github reviewed Nov 25, 2016

View reviewed changes

sam-github suggested changes Nov 25, 2016

View reviewed changes

vsemozhetbyt added 7 commits November 26, 2016 22:53

doc: var => const/let in the buffer.md

df33c79

doc: fix a syntax error in the buffer.md

365ad3c

doc: fix wrong function arguments in the buffer.md

da92b8e

doc: fix copy-paste artifacts in the buffer.md

65abe28

doc: repeat a remark as needed in the buffer.md

625fece

doc: add a variable declaration in the buffer.md

70f9f3b

doc: remove a wrong remark in the buffer.md

a50f3b2

sam-github reviewed Nov 27, 2016

View reviewed changes

sam-github approved these changes Nov 27, 2016

View reviewed changes

vsemozhetbyt added 2 commits November 28, 2016 00:44

doc: fix examples in buffer.md to avoid confusion

41c1a2c

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

doc: remove an extraneous word in the buffer.md

55449d3

vsemozhetbyt mentioned this pull request Dec 3, 2016

doc: var => const in js code examples of addons.md #10092

Closed

2 tasks

silverwind suggested changes Dec 3, 2016

View reviewed changes

doc: fix a wrong note in the buffer.md

8f260ec

silverwind approved these changes Dec 4, 2016

View reviewed changes

addaleax approved these changes Dec 4, 2016

View reviewed changes

Fishrock123 pushed a commit that referenced this pull request Dec 13, 2016

doc: add a variable declaration in the buffer.md

3034038

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

italoacasas mentioned this pull request Dec 15, 2016

v7.3.0 proposal #10277

Merged

MylesBorins added lts-watch-v4.x labels Dec 20, 2016

MylesBorins pushed a commit that referenced this pull request Mar 7, 2017

doc: var => const/let in the buffer.md

7bd19bf

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

MylesBorins pushed a commit that referenced this pull request Mar 7, 2017

doc: fix a syntax error in the buffer.md

a0e87d6

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

MylesBorins pushed a commit that referenced this pull request Mar 7, 2017

doc: fix wrong function arguments in the buffer.md

9354ee5

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

MylesBorins pushed a commit that referenced this pull request Mar 7, 2017

doc: fix copy-paste artifacts in the buffer.md

13fa9af

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

MylesBorins pushed a commit that referenced this pull request Mar 7, 2017

doc: remove a wrong remark in the buffer.md

95f372f

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

MylesBorins pushed a commit that referenced this pull request Mar 7, 2017

doc: fix a wrong note in the buffer.md

b14bd25

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

MylesBorins added dont-land-on-v4.x and removed lts-watch-v4.x labels Mar 7, 2017

MylesBorins pushed a commit that referenced this pull request Mar 9, 2017

doc: var => const/let in the buffer.md

b36c315

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

MylesBorins pushed a commit that referenced this pull request Mar 9, 2017

doc: fix a syntax error in the buffer.md

e94abae

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

MylesBorins pushed a commit that referenced this pull request Mar 9, 2017

doc: fix wrong function arguments in the buffer.md

a2b40ad

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

MylesBorins pushed a commit that referenced this pull request Mar 9, 2017

doc: fix copy-paste artifacts in the buffer.md

8af811f

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

MylesBorins pushed a commit that referenced this pull request Mar 9, 2017

doc: remove a wrong remark in the buffer.md

020c90e

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

MylesBorins pushed a commit that referenced this pull request Mar 9, 2017

doc: fix a wrong note in the buffer.md

4995a81

PR-URL: #9795 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

MylesBorins mentioned this pull request Mar 9, 2017

v6.10.1 proposal #11759

Merged

doc: small fixes in the buffer.md #9795

doc: small fixes in the buffer.md #9795

Conversation

vsemozhetbyt commented Nov 25, 2016 • edited Loading

Checklist

Affected core subsystem(s)

Description of change

Choose a reason for hiding this comment

vsemozhetbyt Nov 25, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt Nov 25, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt Nov 25, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt Nov 25, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sam-github left a comment

Choose a reason for hiding this comment

vsemozhetbyt commented Nov 25, 2016 • edited Loading

vsemozhetbyt commented Nov 25, 2016 • edited Loading

vsemozhetbyt commented Nov 26, 2016

vsemozhetbyt commented Nov 27, 2016

Choose a reason for hiding this comment

sam-github commented Nov 27, 2016

vsemozhetbyt commented Nov 30, 2016

sam-github commented Nov 30, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

silverwind Dec 3, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt commented Dec 4, 2016

silverwind commented Dec 4, 2016

MylesBorins commented Dec 20, 2016

vsemozhetbyt commented Nov 25, 2016 •

edited

Loading

vsemozhetbyt Nov 25, 2016 •

edited

Loading

vsemozhetbyt Nov 25, 2016 •

edited

Loading

vsemozhetbyt Nov 25, 2016 •

edited

Loading

vsemozhetbyt Nov 25, 2016 •

edited

Loading

vsemozhetbyt commented Nov 25, 2016 •

edited

Loading

vsemozhetbyt commented Nov 25, 2016 •

edited

Loading

silverwind Dec 3, 2016 •

edited

Loading