doc: add Buffer#subarray() and add note about Uint8Array#slice()

[gfx]

refs: #28087

• Added document for Buffer#subarray(); its content is just copied from #slice()
• Changed document for Buffer#slice() because of its incompatibility with its superclass's method, and also added how to use Uint8Array.prototype.slice() to get a copy of slice

Checklist

• [ ] make -j4 test (UNIX), or vcbuild test (Windows) passes
• [ ] tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

[mscdex]

I don't think we need to document inherited methods like subarray().

If anything, only the new note should be added to the description for slice().

[gfx]

@mscdex

I don't think we need to document inherited methods like subarray().

Really?

There are lots of methods and properties in the doc, directly inherited from Uint8Array, for example:

• buf[i]
• buf.buffer
• buf.byteOffset
• buf.length
• buf.entries()
• buf.keys()
• buf.values()

I think #subarray() is also a method to be known, which is compatible with Uint8Array.

[mscdex]

Right, I don't agree those need to be there either.

IMO there is no need to duplicate documentation (already available at places like MDN) for those properties/methods unless there is some behavioral/semantic difference with node's implementation. Making it clear that Buffer inherits from Uint8Array and providing a link to documentation for the latter should be sufficient really.

Even within node's own documentation we generally don't duplicate between similar/super objects (e.g. tls.TLSSocket does not show everything inherited from net.Socket).

[sam-github]

#28101 (comment) makes sense to me. I wonder, do our docs predate Buffer being derived from Uint8Array?

[mscdex]

do our docs predate Buffer being derived from Uint8Array?

Definitely.

[addaleax]

I think it’s a good change, because it ultimately encourages using a standardized TypedArray method over our non-standard different-behaviour override of another TypedArray method.

[gfx]

Applied suggested changes!

[addaleax]

I’ll land this tomorrow if there are no objections to that.

[gfx]

Thanks, @Trott !

[Trott]

Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/3672/

[Trott]

Landed in ee16787