doc: improve buf.fill() documentation

* Improve prepositions.
* Wrap at 80 characters.
* Formalize colloquial text.
* Remove unnecessary sentence.
* Use colons to introduce example code.

PR-URL: https://github.com/nodejs/node/pull/19846
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Beth Griggs <Bethany.Griggs@uk.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

1 files changed, 9 insertions, 8 deletions

diff --git a/doc/api/buffer.md b/doc/api/buffer.md
index c0df6e556b..d3a92f6d35 100644
--- a/doc/api/buffer.md
+++ b/doc/api/buffer.md
@@ -1164,16 +1164,17 @@ changes:
     description: The `encoding` parameter is supported now.
 -->
 
-* `value` {string|Buffer|integer} The value to fill `buf` with.
-* `offset` {integer} Number of bytes to skip before starting to fill `buf`. **Default:** `0`.
-* `end` {integer} Where to stop filling `buf` (not inclusive). **Default:** [`buf.length`].
-* `encoding` {string} If `value` is a string, this is its encoding.
+* `value` {string|Buffer|integer} The value with which to fill `buf`.
+* `offset` {integer} Number of bytes to skip before starting to fill `buf`.
+  **Default:** `0`.
+* `end` {integer} Where to stop filling `buf` (not inclusive). **Default:**
+  [`buf.length`].
+* `encoding` {string} The encoding for `value` if `value` is a string.
   **Default:** `'utf8'`.
 * Returns: {Buffer} A reference to `buf`.
 
 Fills `buf` with the specified `value`. If the `offset` and `end` are not given,
-the entire `buf` will be filled. This is meant to be a small simplification to
-allow the creation and filling of a `Buffer` to be done on a single line.
+the entire `buf` will be filled:
 
 ```js
 // Fill a `Buffer` with the ASCII character 'h'.
@@ -1184,10 +1185,10 @@ console.log(b.toString());
 // Prints: hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh
 ```
 
-`value` is coerced to a `uint32` value if it is not a String or Integer.
+`value` is coerced to a `uint32` value if it is not a string or integer.
 
 If the final write of a `fill()` operation falls on a multi-byte character,
-then only the first bytes of that character that fit into `buf` are written.
+then only the bytes of that character that fit into `buf` are written:
 
 ```js
 // Fill a `Buffer` with a two-byte character.