doc: make buffer methods styles consistent
authorTimothy Gu <timothygu99@gmail.com>
Tue, 26 Jan 2016 03:05:43 +0000 (19:05 -0800)
committerMyles Borins <mborins@us.ibm.com>
Wed, 2 Mar 2016 22:01:11 +0000 (14:01 -0800)
- Maintain alphabetical order
- Add documentation for `offset` and `value` where absent
- Add return value documentation where absent
- Remove redundant "Optional"
- Move defaults to parameter enumerations

PR-URL: https://github.com/nodejs/node/pull/4873
Reviewed-By: James M Snell <jasnell@gmail.com>
doc/api/buffer.markdown

index 8be347a..9296c5b 100644 (file)
@@ -150,7 +150,7 @@ It can be constructed in a variety of ways.
 
 ### new Buffer(array)
 
-* `array` Array
+* `array` {Array}
 
 Allocates a new Buffer using an `array` of octets.
 
@@ -205,7 +205,7 @@ console.log(buf);
 
 ### new Buffer(size)
 
-* `size` Number
+* `size` {Number}
 
 Allocates a new Buffer of `size` bytes.  The `size` must be less than
 or equal to the value of `require('buffer').kMaxLength` (on 64-bit
@@ -230,12 +230,11 @@ console.log(buf);
 
 ### new Buffer(str[, encoding])
 
-* `str` String - string to encode.
-* `encoding` String - encoding to use, Optional.
+* `str` {String} String to encode.
+* `encoding` {String} Default: `'utf8'`
 
 Creates a new Buffer containing the given JavaScript string `str`. If
 provided, the `encoding` parameter identifies the strings character encoding.
-If not provided, `encoding` defaults to `'utf8'`.
 
 ```js
 const buf1 = new Buffer('this is a tést');
@@ -251,13 +250,13 @@ console.log(buf2.toString());
 
 ### Class Method: Buffer.byteLength(string[, encoding])
 
-* `string` String
-* `encoding` String, Optional, Default: 'utf8'
-* Return: Number
+* `string` {String}
+* `encoding` {String} Default: `'utf8'`
+* Return: {Number}
 
-Returns the actual byte length of a string. If not specified, `encoding`
-defaults to `'utf8'`. This is not the same as [`String.prototype.length`][]
-since that returns the number of *characters* in a string.
+Returns the actual byte length of a string. This is not the same as
+[`String.prototype.length`][] since that returns the number of *characters* in
+a string.
 
 Example:
 
@@ -274,6 +273,7 @@ console.log(`${str}: ${str.length} characters, ` +
 
 * `buf1` {Buffer}
 * `buf2` {Buffer}
+* Return: {Number}
 
 Compares `buf1` to `buf2` typically for the purpose of sorting arrays of
 Buffers. This is equivalent is calling `buf1.compare(buf2)`.
@@ -287,6 +287,7 @@ arr.sort(Buffer.compare);
 
 * `list` {Array} List of Buffer objects to concat
 * `totalLength` {Number} Total length of the Buffers in the list when concatenated
+* Return: {Buffer}
 
 Returns a new Buffer which is the result of concatenating all the Buffers in
 the `list` together.
@@ -318,85 +319,19 @@ console.log(bufA.length);
 
 ### Class Method: Buffer.isBuffer(obj)
 
-* `obj` Object
-* Return: Boolean
+* `obj` {Object}
+* Return: {Boolean}
 
 Returns 'true' if `obj` is a Buffer.
 
 ### Class Method: Buffer.isEncoding(encoding)
 
 * `encoding` {String} The encoding string to test
+* Return: {Boolean}
 
 Returns true if the `encoding` is a valid encoding argument, or false
 otherwise.
 
-### buffer.entries()
-
-Creates and returns an [iterator][] of `[index, byte]` pairs from the Buffer
-contents.
-
-```js
-const buf = new Buffer('buffer');
-for (var pair of buf.entries()) {
-  console.log(pair);
-}
-// prints:
-//   [0, 98]
-//   [1, 117]
-//   [2, 102]
-//   [3, 102]
-//   [4, 101]
-//   [5, 114]
-```
-
-### buffer.keys()
-
-Creates and returns an [iterator][] of Buffer keys (indices).
-
-```js
-const buf = new Buffer('buffer');
-for (var key of buf.keys()) {
-  console.log(key);
-}
-// prints:
-//   0
-//   1
-//   2
-//   3
-//   4
-//   5
-```
-
-### buffer.values()
-
-Creates and returns an [iterator][] for Buffer values (bytes). This function is
-called automatically when the Buffer is used in a `for..of` statement.
-
-```js
-const buf = new Buffer('buffer');
-for (var value of buf.values()) {
-  console.log(value);
-}
-// prints:
-//   98
-//   117
-//   102
-//   102
-//   101
-//   114
-
-for (var value of buf) {
-  console.log(value);
-}
-// prints:
-//   98
-//   117
-//   102
-//   102
-//   101
-//   114
-```
-
 ### buf[index]
 
 <!--type=property-->
@@ -423,6 +358,7 @@ console.log(buf);
 ### buf.compare(otherBuffer)
 
 * `otherBuffer` {Buffer}
+* Return: {Number}
 
 Compares two Buffer instances and returns a number indicating whether `buf`
 comes before, after, or is the same as the `otherBuffer` in sort order.
@@ -454,17 +390,14 @@ console.log(buf2.compare(buf3));
 
 ### buf.copy(targetBuffer[, targetStart][, sourceStart][, sourceEnd])
 
-* `targetBuffer` Buffer object - Buffer to copy into
-* `targetStart` Number, Optional, Default: 0
-* `sourceStart` Number, Optional, Default: 0
-* `sourceEnd` Number, Optional, Default: `buffer.length`
+* `targetBuffer` {Buffer} Buffer to copy into
+* `targetStart` {Number} Default: 0
+* `sourceStart` {Number} Default: 0
+* `sourceEnd` {Number} Default: `buffer.length`
+* Return: {Number} The number of bytes copied.
 
 Copies data from a region of this Buffer to a region in the target Buffer even
-if the target memory region overlaps with the source. If `undefined`, the
-`targetStart` and `sourceStart` parameters default to `0` while `sourceEnd`
-defaults to `buffer.length`.
-
-Returns the number of bytes copied.
+if the target memory region overlaps with the source.
 
 Example: build two Buffers, then copy `buf1` from byte 16 through byte 19
 into `buf2`, starting at the 8th byte in `buf2`.
@@ -498,9 +431,31 @@ console.log(buf.toString());
 // efghijghijklmnopqrstuvwxyz
 ```
 
+### buf.entries()
+
+* Return: {Iterator}
+
+Creates and returns an [iterator][] of `[index, byte]` pairs from the Buffer
+contents.
+
+```js
+const buf = new Buffer('buffer');
+for (var pair of buf.entries()) {
+  console.log(pair);
+}
+// prints:
+//   [0, 98]
+//   [1, 117]
+//   [2, 102]
+//   [3, 102]
+//   [4, 101]
+//   [5, 114]
+```
+
 ### buf.equals(otherBuffer)
 
 * `otherBuffer` {Buffer}
+* Return: {Boolean}
 
 Returns a boolean indicating whether `this` and `otherBuffer` have exactly the
 same bytes.
@@ -518,13 +473,14 @@ console.log(buf1.equals(buf3));
 
 ### buf.fill(value[, offset][, end])
 
-* `value`
-* `offset` Number, Optional
-* `end` Number, Optional
+* `value` {String or Number}
+* `offset` {Number} Default: 0
+* `end` {Number} Default: `buffer.length`
+* Return: {Buffer}
 
-Fills the Buffer with the specified value. If the `offset` (defaults to `0`)
-and `end` (defaults to `buffer.length`) are not given it will fill the entire
-Buffer. The method returns a reference to the Buffer so calls can be chained.
+Fills the Buffer with the specified value. If the `offset` and `end` are not
+given it will fill the entire Buffer. The method returns a reference to the
+Buffer so calls can be chained.
 
 ```js
 const b = new Buffer(50).fill('h');
@@ -534,10 +490,10 @@ console.log(b.toString());
 
 ### buf.indexOf(value[, byteOffset][, encoding])
 
-* `value` String, Buffer or Number
-* `byteOffset` Number, Optional, Default: 0
-* `encoding` String, Optional, Default: `utf8`
-* Return: Number
+* `value` {String, Buffer or Number}
+* `byteOffset` {Number} Default: 0
+* `encoding` {String} Default: `'utf8'`
+* Return: {Number}
 
 Operates similar to [`Array#indexOf()`][] in that it returns either the
 starting index position of `value` in Buffer or `-1` if the Buffer does not
@@ -571,9 +527,10 @@ utf16Buffer.indexOf('\u03a3', -4, 'ucs2');
 
 ### buf.includes(value[, byteOffset][, encoding])
 
-* `value` String, Buffer or Number
-* `byteOffset` Number, Optional, Default: 0
-* `encoding` String, Optional, Default: 'utf8'
+* `value` {String, Buffer or Number}
+* `byteOffset` {Number} Default: 0
+* `encoding` {String} Default: `'utf8'`
+* Return: {Boolean}
 
 Operates similar to [Array#includes()][]. The `value` can be a String, Buffer
 or Number. Strings are interpreted as UTF8 unless overridden with the
@@ -600,9 +557,29 @@ buf.includes('this', 4);
   // returns false
 ```
 
+### buf.keys()
+
+* Return: {Iterator}
+
+Creates and returns an [iterator][] of Buffer keys (indices).
+
+```js
+const buf = new Buffer('buffer');
+for (var key of buf.keys()) {
+  console.log(key);
+}
+// prints:
+//   0
+//   1
+//   2
+//   3
+//   4
+//   5
+```
+
 ### buf.length
 
-* Number
+* {Number}
 
 Returns the amount of memory allocated for the Buffer in number of bytes. Note
 that this does not necessarily reflect the amount of usable data within the
@@ -638,17 +615,16 @@ console.log(buf.length);
 ### buf.readDoubleBE(offset[, noAssert])
 ### buf.readDoubleLE(offset[, noAssert])
 
-* `offset` Number
-* `noAssert` Boolean, Optional, Default: false
-* Return: Number
+* `offset` {Number} `0 <= offset <= buf.length - 8`
+* `noAssert` {Boolean} Default: false
+* Return: {Number}
 
 Reads a 64-bit double from the Buffer at the specified `offset` with specified
 endian format (`readDoubleBE()` returns big endian, `readDoubleLE()` returns
 little endian).
 
 Setting `noAssert` to `true` skips validation of the `offset`. This allows the
-`offset` to be beyond the end of the Buffer. When not specified, `noAssert`
-defaults to `false`.
+`offset` to be beyond the end of the Buffer.
 
 ```js
 const buf = new Buffer([1,2,3,4,5,6,7,8]);
@@ -667,17 +643,16 @@ buf.readDoubleLE(1, true); // Warning: reads passed end of buffer!
 ### buf.readFloatBE(offset[, noAssert])
 ### buf.readFloatLE(offset[, noAssert])
 
-* `offset` Number
-* `noAssert` Boolean, Optional, Default: false
-* Return: Number
+* `offset` {Number} `0 <= offset <= buf.length - 4`
+* `noAssert` {Boolean} Default: false
+* Return: {Number}
 
 Reads a 32-bit float from the Buffer at the specified `offset` with specified
 endian format (`readFloatBE()` returns big endian, `readFloatLE()` returns
 little endian).
 
 Setting `noAssert` to `true` skips validation of the `offset`. This allows the
-`offset` to be beyond the end of the Buffer. When not specified, `noAssert`
-defaults to `false`.
+`offset` to be beyond the end of the Buffer.
 
 ```js
 const buf = new Buffer([1,2,3,4]);
@@ -695,15 +670,14 @@ buf.readFloatLE(1, true); // Warning: reads passed end of buffer!
 
 ### buf.readInt8(offset[, noAssert])
 
-* `offset` Number
-* `noAssert` Boolean, Optional, Default: false
-* Return: Number
+* `offset` {Number} `0 <= offset <= buf.length - 1`
+* `noAssert` {Boolean} Default: false
+* Return: {Number}
 
 Reads a signed 8-bit integer from the Buffer at the specified `offset`.
 
 Setting `noAssert` to `true` skips validation of the `offset`. This allows the
-`offset` to be beyond the end of the Buffer. When not specified, `noAssert`
-defaults to `false`.
+`offset` to be beyond the end of the Buffer.
 
 Integers read from the Buffer are interpreted as two's complement signed values.
 
@@ -719,17 +693,16 @@ buf.readInt8(1);
 ### buf.readInt16BE(offset[, noAssert])
 ### buf.readInt16LE(offset[, noAssert])
 
-* `offset` Number
-* `noAssert` Boolean, Optional, Default: false
-* Return: Number
+* `offset` {Number} `0 <= offset <= buf.length - 2`
+* `noAssert` {Boolean} Default: false
+* Return: {Number}
 
 Reads a signed 16-bit integer from the Buffer at the specified `offset` with
 the specified endian format (`readInt16BE()` returns big endian,
 `readInt16LE()` returns little endian).
 
 Setting `noAssert` to `true` skips validation of the `offset`. This allows the
-`offset` to be beyond the end of the Buffer. When not specified, `noAssert`
-defaults to `false`.
+`offset` to be beyond the end of the Buffer.
 
 Integers read from the Buffer are interpreted as two's complement signed values.
 
@@ -745,17 +718,16 @@ buf.readInt16LE(1);
 ### buf.readInt32BE(offset[, noAssert])
 ### buf.readInt32LE(offset[, noAssert])
 
-* `offset` Number
-* `noAssert` Boolean, Optional, Default: false
-* Return: Number
+* `offset` {Number} `0 <= offset <= buf.length - 4`
+* `noAssert` {Boolean} Default: false
+* Return: {Number}
 
 Reads a signed 32-bit integer from the Buffer at the specified `offset` with
 the specified endian format (`readInt32BE()` returns big endian,
 `readInt32LE()` returns little endian).
 
 Setting `noAssert` to `true` skips validation of the `offset`. This allows the
-`offset` to be beyond the end of the Buffer. When not specified, `noAssert`
-defaults to `false`.
+`offset` to be beyond the end of the Buffer.
 
 Integers read from the Buffer are interpreted as two's complement signed values.
 
@@ -771,7 +743,7 @@ buf.readInt32LE(1);
 ### buf.readIntBE(offset, byteLength[, noAssert])
 ### buf.readIntLE(offset, byteLength[, noAssert])
 
-* `offset` {Number} `0 <= offset <= buf.length`
+* `offset` {Number} `0 <= offset <= buf.length - byteLength`
 * `byteLength` {Number} `0 < byteLength <= 6`
 * `noAssert` {Boolean} Default: false
 * Return: {Number}
@@ -792,20 +764,18 @@ buf.readIntBE(0, 6).toString(16);
 ```
 
 Setting `noAssert` to `true` skips validation of the `offset`. This allows the
-`offset` to be beyond the end of the Buffer. When not specified, `noAssert`
-defaults to `false`.
+`offset` to be beyond the end of the Buffer.
 
 ### buf.readUInt8(offset[, noAssert])
 
-* `offset` Number
-* `noAssert` Boolean, Optional, Default: false
-* Return: Number
+* `offset` {Number} `0 <= offset <= buf.length - 1`
+* `noAssert` {Boolean} Default: false
+* Return: {Number}
 
 Reads an unsigned 8-bit integer from the Buffer at the specified `offset`.
 
 Setting `noAssert` to `true` skips validation of the `offset`. This allows the
-`offset` to be beyond the end of the Buffer. When not specified, `noAssert`
-defaults to `false`.
+`offset` to be beyond the end of the Buffer.
 
 ```js
 const buf = new Buffer([1,-2,3,4]);
@@ -819,17 +789,16 @@ buf.readUInt8(1);
 ### buf.readUInt16BE(offset[, noAssert])
 ### buf.readUInt16LE(offset[, noAssert])
 
-* `offset` Number
-* `noAssert` Boolean, Optional, Default: false
-* Return: Number
+* `offset` {Number} `0 <= offset <= buf.length - 2`
+* `noAssert` {Boolean} Default: false
+* Return: {Number}
 
 Reads an unsigned 16-bit integer from the Buffer at the specified `offset` with
 specified endian format (`readInt32BE()` returns big endian,
 `readInt32LE()` returns little endian).
 
 Setting `noAssert` to `true` skips validation of the `offset`. This allows the
-`offset` to be beyond the end of the Buffer. When not specified, `noAssert`
-defaults to `false`.
+`offset` to be beyond the end of the Buffer.
 
 Example:
 
@@ -853,17 +822,16 @@ buf.readUInt16LE(2);
 ### buf.readUInt32BE(offset[, noAssert])
 ### buf.readUInt32LE(offset[, noAssert])
 
-* `offset` Number
-* `noAssert` Boolean, Optional, Default: false
-* Return: Number
+* `offset` {Number} `0 <= offset <= buf.length - 4`
+* `noAssert` {Boolean} Default: false
+* Return: {Number}
 
 Reads an unsigned 32-bit integer from the Buffer at the specified `offset` with
 specified endian format (`readInt32BE()` returns big endian,
 `readInt32LE()` returns little endian).
 
 Setting `noAssert` to `true` skips validation of the `offset`. This allows the
-`offset` to be beyond the end of the Buffer. When not specified, `noAssert`
-defaults to `false`.
+`offset` to be beyond the end of the Buffer.
 
 Example:
 
@@ -879,7 +847,7 @@ console.log(buf.readUInt32LE(0));
 ### buf.readUIntBE(offset, byteLength[, noAssert])
 ### buf.readUIntLE(offset, byteLength[, noAssert])
 
-* `offset` {Number} `0 <= offset <= buf.length`
+* `offset` {Number} `0 <= offset <= buf.length - byteLength`
 * `byteLength` {Number} `0 < byteLength <= 6`
 * `noAssert` {Boolean} Default: false
 * Return: {Number}
@@ -900,19 +868,19 @@ buf.readUIntBE(0, 6).toString(16);
 ```
 
 Setting `noAssert` to `true` skips validation of the `offset`. This allows the
-`offset` to be beyond the end of the Buffer. When not specified, `noAssert`
-defaults to `false`.
+`offset` to be beyond the end of the Buffer.
 
 ### buf.slice([start[, end]])
 
-* `start` Number, Optional, Default: 0
-* `end` Number, Optional, Default: `buffer.length`
+* `start` {Number} Default: 0
+* `end` {Number} Default: `buffer.length`
+* Return: {Buffer}
 
-Returns a new Buffer that references the same memory as the original, but offset
-and cropped by the `start` (defaults to `0`) and `end` (defaults to
-`buffer.length`) indexes.
+Returns a new Buffer that references the same memory as the original, but
+offset and cropped by the `start` and `end` indices.
 
-**Note that modifying the new Buffer slice will modify the memory in the original Buffer because the allocated memory of the two objects overlap.**
+**Note that modifying the new Buffer slice will modify the memory in the
+original Buffer because the allocated memory of the two objects overlap.**
 
 Example: build a Buffer with the ASCII alphabet, take a slice, then modify one
 byte from the original Buffer.
@@ -948,14 +916,13 @@ buf.slice(-5, -2).toString();
 
 ### buf.toString([encoding][, start][, end])
 
-* `encoding` String, Optional, Default: 'utf8'
-* `start` Number, Optional, Default: 0
-* `end` Number, Optional, Default: `buffer.length`
+* `encoding` {String} Default: `'utf8'`
+* `start` {Number} Default: 0
+* `end` {Number} Default: `buffer.length`
+* Return: {String}
 
 Decodes and returns a string from the Buffer data using the specified
-character set `encoding`. If `encoding` is `undefined` or `null`, then
-`encoding` defaults to `'utf8'`. The `start` and `end` parameters default to
-`0` and `buffer.length` when `undefined`.
+character set `encoding`.
 
 ```js
 const buf = new Buffer(26);
@@ -974,6 +941,8 @@ buf.toString(undefined,0,5);
 
 ### buf.toJSON()
 
+* Return: {Object}
+
 Returns a JSON representation of the Buffer instance.  `JSON.stringify`
 implicitly calls this function when stringifying a Buffer instance.
 
@@ -996,20 +965,51 @@ console.log(copy.toString());
 // Prints: 'test'
 ```
 
+### buf.values()
+
+* Return: {Iterator}
+
+Creates and returns an [iterator][] for Buffer values (bytes). This function is
+called automatically when the Buffer is used in a `for..of` statement.
+
+```js
+const buf = new Buffer('buffer');
+for (var value of buf.values()) {
+  console.log(value);
+}
+// prints:
+//   98
+//   117
+//   102
+//   102
+//   101
+//   114
+
+for (var value of buf) {
+  console.log(value);
+}
+// prints:
+//   98
+//   117
+//   102
+//   102
+//   101
+//   114
+```
+
 ### buf.write(string[, offset][, length][, encoding])
 
-* `string` String - data to be written to buffer
-* `offset` Number, Optional, Default: 0
-* `length` Number, Optional, Default: `buffer.length - offset`
-* `encoding` String, Optional, Default: 'utf8'
+* `string` {String} Bytes to be written to buffer
+* `offset` {Number} Default: 0
+* `length` {Number} Default: `buffer.length - offset`
+* `encoding` {String} Default: `'utf8'`
+* Return: {Number} Numbers of bytes written
 
 Writes `string` to the Buffer at `offset` using the given `encoding`.
-When undefined, `offset` defaults to `0`, and `encoding` defaults to `'utf8'`.
-The `length` parameter is the number of bytes to write, when undefined `length`
-defaults to `buffer.length - offset`. If the Buffer did not contain enough
-space to fit the entire string, only a partial amount of the string will be
-written however, it will not write only partially encoded characters. The
-return value indicates the number of octets written.
+The `length` parameter is the number of bytes to write. If the Buffer did not
+contain enough space to fit the entire string, only a partial amount of the
+string will be written however, it will not write only partially encoded
+characters.
 
 ```js
 const buf = new Buffer(256);
@@ -1021,9 +1021,10 @@ console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`);
 ### buf.writeDoubleBE(value, offset[, noAssert])
 ### buf.writeDoubleLE(value, offset[, noAssert])
 
-* `value` Number
-* `offset` Number
-* `noAssert` Boolean, Optional, Default: false
+* `value` {Number} Bytes to be written to Buffer
+* `offset` {Number} `0 <= offset <= buf.length - 8`
+* `noAssert` {Boolean} Default: false
+* Return: {Number} Numbers of bytes written
 
 Writes `value` to the Buffer at the specified `offset` with specified endian
 format (`writeDoubleBE()` writes big endian, `writeDoubleLE()` writes little
@@ -1032,7 +1033,7 @@ endian). The `value` argument must be a valid 64-bit double.
 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 that `value` may be too large for the specific function and `offset` may be
 beyond the end of the Buffer leading to the values being silently dropped. This
-should not be used unless you are certain of correctness. Defaults to `false`.
+should not be used unless you are certain of correctness.
 
 Example:
 
@@ -1052,9 +1053,10 @@ console.log(buf);
 ### buf.writeFloatBE(value, offset[, noAssert])
 ### buf.writeFloatLE(value, offset[, noAssert])
 
-* `value` Number
-* `offset` Number
-* `noAssert` Boolean, Optional, Default: false
+* `value` {Number} Bytes to be written to Buffer
+* `offset` {Number} `0 <= offset <= buf.length - 4`
+* `noAssert` {Boolean} Default: false
+* Return: {Number} Numbers of bytes written
 
 Writes `value` to the Buffer at the specified `offset` with specified endian
 format (`writeFloatBE()` writes big endian, `writeFloatLE()` writes little
@@ -1064,7 +1066,7 @@ float.
 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 that `value` may be too large for the specific function and `offset` may be
 beyond the end of the Buffer leading to the values being silently dropped. This
-should not be used unless you are certain of correctness. Defaults to `false`.
+should not be used unless you are certain of correctness.
 
 Example:
 
@@ -1083,9 +1085,10 @@ console.log(buf);
 
 ### buf.writeInt8(value, offset[, noAssert])
 
-* `value` Number
-* `offset` Number
-* `noAssert` Boolean, Optional, Default: false
+* `value` {Number} Bytes to be written to Buffer
+* `offset` {Number} `0 <= offset <= buf.length - 1`
+* `noAssert` {Boolean} Default: false
+* Return: {Number} Numbers of bytes written
 
 Writes `value` to the Buffer at the specified `offset`. The `value` must be a
 valid signed 8-bit integer.
@@ -1093,7 +1096,7 @@ valid signed 8-bit integer.
 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 that `value` may be too large for the specific function and `offset` may be
 beyond the end of the Buffer leading to the values being silently dropped. This
-should not be used unless you are certain of correctness. Defaults to `false`.
+should not be used unless you are certain of correctness.
 
 The `value` is interpreted and written as a two's complement signed integer.
 
@@ -1108,9 +1111,10 @@ console.log(buf);
 ### buf.writeInt16BE(value, offset[, noAssert])
 ### buf.writeInt16LE(value, offset[, noAssert])
 
-* `value` Number
-* `offset` Number
-* `noAssert` Boolean, Optional, Default: false
+* `value` {Number} Bytes to be written to Buffer
+* `offset` {Number} `0 <= offset <= buf.length - 2`
+* `noAssert` {Boolean} Default: false
+* Return: {Number} Numbers of bytes written
 
 Writes `value` to the Buffer at the specified `offset` with specified endian
 format (`writeInt16BE()` writes big endian, `writeInt16LE()` writes little
@@ -1119,7 +1123,7 @@ endian). The `value` must be a valid signed 16-bit integer.
 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 that `value` may be too large for the specific function and `offset` may be
 beyond the end of the Buffer leading to the values being silently dropped. This
-should not be used unless you are certain of correctness. Defaults to `false`.
+should not be used unless you are certain of correctness.
 
 The `value` is interpreted and written as a two's complement signed integer.
 
@@ -1134,9 +1138,10 @@ console.log(buf);
 ### buf.writeInt32BE(value, offset[, noAssert])
 ### buf.writeInt32LE(value, offset[, noAssert])
 
-* `value` Number
-* `offset` Number
-* `noAssert` Boolean, Optional, Default: false
+* `value` {Number} Bytes to be written to Buffer
+* `offset` {Number} `0 <= offset <= buf.length - 4`
+* `noAssert` {Boolean} Default: false
+* Return: {Number} Numbers of bytes written
 
 Writes `value` to the Buffer at the specified `offset` with specified endian
 format (`writeInt32BE()` writes big endian, `writeInt32LE()` writes little
@@ -1145,7 +1150,7 @@ endian). The `value` must be a valid signed 32-bit integer.
 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 that `value` may be too large for the specific function and `offset` may be
 beyond the end of the Buffer leading to the values being silently dropped. This
-should not be used unless you are certain of correctness. Defaults to `false`.
+should not be used unless you are certain of correctness.
 
 The `value` is interpreted and written as a two's complement signed integer.
 
@@ -1161,10 +1166,10 @@ console.log(buf);
 ### buf.writeIntLE(value, offset, byteLength[, noAssert])
 
 * `value` {Number} Bytes to be written to Buffer
-* `offset` {Number} `0 <= offset <= buf.length`
+* `offset` {Number} `0 <= offset <= buf.length - byteLength`
 * `byteLength` {Number} `0 < byteLength <= 6`
 * `noAssert` {Boolean} Default: false
-* Return: {Number}
+* Return: {Number} Numbers of bytes written
 
 Writes `value` to the Buffer at the specified `offset` and `byteLength`.
 Supports up to 48 bits of accuracy. For example:
@@ -1184,13 +1189,14 @@ console.log(buf2);
 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 that `value` may be too large for the specific function and `offset` may be
 beyond the end of the Buffer leading to the values being silently dropped. This
-should not be used unless you are certain of correctness. Defaults to `false`.
+should not be used unless you are certain of correctness.
 
 ### buf.writeUInt8(value, offset[, noAssert])
 
-* `value` Number
-* `offset` Number
-* `noAssert` Boolean, Optional, Default: false
+* `value` {Number} Bytes to be written to Buffer
+* `offset` {Number} `0 <= offset <= buf.length - 1`
+* `noAssert` {Boolean} Default: false
+* Return: {Number} Numbers of bytes written
 
 Writes `value` to the Buffer at the specified `offset`. The `value` must be a
 valid unsigned 8-bit integer.
@@ -1198,7 +1204,7 @@ valid unsigned 8-bit integer.
 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 that `value` may be too large for the specific function and `offset` may be
 beyond the end of the Buffer leading to the values being silently dropped. This
-should not be used unless you are certain of correctness. Defaults to `false`.
+should not be used unless you are certain of correctness.
 
 Example:
 
@@ -1216,9 +1222,10 @@ console.log(buf);
 ### buf.writeUInt16BE(value, offset[, noAssert])
 ### buf.writeUInt16LE(value, offset[, noAssert])
 
-* `value` Number
-* `offset` Number
-* `noAssert` Boolean, Optional, Default: false
+* `value` {Number} Bytes to be written to Buffer
+* `offset` {Number} `0 <= offset <= buf.length - 2`
+* `noAssert` {Boolean} Default: false
+* Return: {Number} Numbers of bytes written
 
 Writes `value` to the Buffer at the specified `offset` with specified endian
 format (`writeUInt16BE()` writes big endian, `writeUInt16LE()` writes little
@@ -1227,7 +1234,7 @@ endian). The `value` must be a valid unsigned 16-bit integer.
 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 that `value` may be too large for the specific function and `offset` may be
 beyond the end of the Buffer leading to the values being silently dropped. This
-should not be used unless you are certain of correctness. Defaults to `false`.
+should not be used unless you are certain of correctness.
 
 Example:
 
@@ -1249,9 +1256,10 @@ console.log(buf);
 ### buf.writeUInt32BE(value, offset[, noAssert])
 ### buf.writeUInt32LE(value, offset[, noAssert])
 
-* `value` Number
-* `offset` Number
-* `noAssert` Boolean, Optional, Default: false
+* `value` {Number} Bytes to be written to Buffer
+* `offset` {Number} `0 <= offset <= buf.length - 4`
+* `noAssert` {Boolean} Default: false
+* Return: {Number} Numbers of bytes written
 
 Writes `value` to the Buffer at the specified `offset` with specified endian
 format (`writeUInt32BE()` writes big endian, `writeUInt32LE()` writes little
@@ -1260,7 +1268,7 @@ endian). The `value` must be a valid unsigned 32-bit integer.
 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 that `value` may be too large for the specific function and `offset` may be
 beyond the end of the Buffer leading to the values being silently dropped. This
-should not be used unless you are certain of correctness. Defaults to `false`.
+should not be used unless you are certain of correctness.
 
 Example:
 
@@ -1281,10 +1289,10 @@ console.log(buf);
 ### buf.writeUIntLE(value, offset, byteLength[, noAssert])
 
 * `value` {Number} Bytes to be written to Buffer
-* `offset` {Number} `0 <= offset <= buf.length`
+* `offset` {Number} `0 <= offset <= buf.length - byteLength`
 * `byteLength` {Number} `0 < byteLength <= 6`
 * `noAssert` {Boolean} Default: false
-* Return: {Number}
+* Return: {Number} Numbers of bytes written
 
 Writes `value` to the Buffer at the specified `offset` and `byteLength`.
 Supports up to 48 bits of accuracy. For example:
@@ -1299,11 +1307,11 @@ console.log(buf);
 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 that `value` may be too large for the specific function and `offset` may be
 beyond the end of the Buffer leading to the values being silently dropped. This
-should not be used unless you are certain of correctness. Defaults to `false`.
+should not be used unless you are certain of correctness.
 
 ## buffer.INSPECT_MAX_BYTES
 
-* Number, Default: 50
+* {Number} Default: 50
 
 Returns the maximum number of bytes that will be returned when
 `buffer.inspect()` is called. This can be overridden by user modules. See