Skip to content

doc: improve buf.indexOf() documentation style #19861

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

Closed
Trott wants to merge 1 commit into from
Closed

doc: improve buf.indexOf() documentation style #19861

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions doc/api/buffer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1258,10 +1258,10 @@ changes:

* `value` {string|Buffer|Uint8Array|integer} What to search for.
* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`.
* `encoding` {string} If `value` is a string, this is its encoding.
* `encoding` {string} The encoding of `value` if `value` is a string.
Copy link
Member

@addaleax addaleax Apr 7, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

nit: I’d say something like If `value` is a string, this encoding is used to look it up in the buffer., or something else that doesn’t sound like the encoding is a inherent to the string value itself

Copy link
Member Author

@Trott Trott Apr 7, 2018

Choose a reason for hiding this comment

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

@addaleax Maybe this? If `value` is a string, this is the encoding used to convert `value` to a binary representation before searching for `value` in `buf`?

Copy link
Member Author

@Trott Trott Apr 7, 2018

Choose a reason for hiding this comment

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

Hmmm...except my wording possibly sounds like value is mutated...

Copy link
Member

@addaleax addaleax Apr 7, 2018

Choose a reason for hiding this comment

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

@Trott Yeah, good point. How about: If `value` is a string, this function looks for the representation of `value` in `encoding`.? It’s less ambiguous and arguably captures the semantics better, but it might also be harder to understand what “representation” means here?

**Default:** `'utf8'`.
* Returns: {integer} The index of the first occurrence of `value` in `buf` or `-1`
if `buf` does not contain `value`.
* Returns: {integer} The index of the first occurrence of `value` in `buf` or
`-1` if `buf` does not contain `value`.

If `value` is:

Expand Down Expand Up @@ -1300,9 +1300,9 @@ If `value` is not a string, number, or `Buffer`, this method will throw a
`TypeError`. If `value` is a number, it will be coerced to a valid byte value,
an integer between 0 and 255.

If `byteOffset` is not a number, it will be coerced to a number. Any arguments
that coerce to `NaN` or 0, like `{}`, `[]`, `null` or `undefined`, will search
the whole buffer. This behavior matches [`String#indexOf()`].
If `byteOffset` is not a number, it will be coerced to a number. If the result
of coercion is `NaN` or `0`, then the entire buffer will be searched. This
behavior matches [`String#indexOf()`].

```js
const b = Buffer.from('abcdef');
Expand Down