Documentation: Unclear if Buffer buf[i] is bounds-checked

[joliss]

From the buf[i] documentation for Buffer, it's unclear whether the following code produces undefined behavior due to out-of-bounds access or does nothing:

new Buffer('')[1000] = 42

I think this should be documented.

(I assume it's bounds-checked since console.log(new Buffer('')[1000]) prints undefined rather than 0, but I haven't checked the source.)

[seishun]

That part of the documentation is a relic from the past when Buffer didn't inherit from Uint8Array. Now it's technically unnecessary since the behavior of Buffer's array index syntax is exactly as described in ECMAScript 2015 spec. Maybe it should be noted that buf[i] is inherited from Uint8Array in the docs though. /cc @nodejs/collaborators

[ronkorving]

@seishun I would argue though that people shouldn't have to look at 2 sets of documentation (Buffer and Uint8Array) just to figure out what the behavior is. That indirection is not particularly user friendly I think.

[seishun]

@ronkorving I agree that basic information about buf[i] should be present in the Buffer documentation, but we should draw the line somewhere. For example, do we want to provide detailed information about how indexed access on a Buffer always ignores the prototype chain? That would take up a lot of space, and most people don't care about such fine details. And those who do would probably prefer to read the spec rather than its retelling in the Node.js docs.

[ronkorving]

I do think that array-like-access should be documented to say whether it will throw or return undefined when out of bounds. But let's get some more input from others on this.

[trevnorris]

The documentation does have the buf[index] section, so would be easy enough to include it there.