doc: Use .prototype. for consistency

[VoltrexKeyva]

Most of the documentation uses the property accessor (.) or .prototype. instead of # to point out some methods or properties (e.g. Buffer.alloc()), there's some that uses (Buffer#alloc()), this is a small change but just for the sake of consistency.

[mscdex]

-1 I believe the reason for the # is that in some cases it makes more sense to refer to a Class method generally, especially when there is no (specific) instance to be referenced.

Changing the # to a . can make things more confusing. For example: changing Buffer#slice() to Buffer.slice() makes it appear as though there is a slice() available on the Buffer constructor, when it fact it's a prototype/instance method instead.

[VoltrexKeyva]

-1 I believe the reason for the # is that in some cases it makes more sense to refer to a Class method generally, especially when there is no (specific) instance to be referenced.

Changing the # to a . can make things more confusing. For example: changing Buffer#slice() to Buffer.slice() makes it appear as though there is a slice() available on the Buffer constructor, when it fact it's a prototype/instance method instead.

I mean, it doesn't make much difference really, I don't see anyone thinking that # means something else other than a dot since in most projects if they're even used, they're considered as a dot, well notation really, but this could be improved by either puting the word prototype (e.g. Buffer.prototype.slice()), or it could be <Buffer>.slice(), but overall, yea; not really a bad point.

[DerekNonGeneric]

I have never seen the hash notation to refer to instance methods, so it looked like a typo for me. I wonder if we have been consistent about doing this throughout all of our docs, though (doubtful). Using .prototype. instead of # doesn't really equate to representing an instance though (since the prototype is everpresent).

/cc @nodejs/documentation for more info, please

[VoltrexKeyva]

I went through almost all of the documentation markdown files (/doc/api) and this file seems to be the only file that uses the # as notation for methods of class instances

[DerekNonGeneric]

I have never seen the hash notation to refer to instance methods, so it looked like a typo for me.

I just happened to come across the notation again in the @typescript-eslint/prefer-regexp-exec docs and can confirm that it is definitely not a typo, but an established pattern (altho I have no idea what it is called).

Use the RegExp#exec() method instead.

This suggestion expands to suggesting to use RegExp.prototype.exec, so here it is referring to the RegExp class' internal methods, but whether or not this can refer to any instance methods or not is still beyond me.

It would be nice to know what this notation is called, so we can determine exactly how to use if we do end up using it.

[DerekNonGeneric]

Alright, after a bit of research, it has become clear to me that this change would be illogical since these are not static methods of these classes.

We would need one of the following changes to make it right:

• typedArray.slice() - to make it look like an instance since they're not static (not a fan of this)
• TypedArray.prototype.slice() - to make entirely less confusing, but a little more to read
• TypedArray#slice() - to leave it as the shorter # notation

[ljharb]

The dots are very much incorrect. Either TypedArray.prototype.slice or TypedArray#slice are the only ways they would be described in any documentation in the JS ecosystem.

[VoltrexKeyva]

Alright, after a bit of research, it has become clear to me that this change would be illogical since these are not static methods of these classes.

We would need one of the following changes to make it right:

• typedArray.slice() - to make it look like an instance they are not static (not a fan of this)
• TypedArray.prototype.slice() - to make entirely less confusing, but a little more to read
• TypedArray#slice() - to leave it as JavaScript foo.prototype.bar notation (apparently lol)

I think it would be better to show the instance properties/methods by adding .prototype. since it makes it a lot less confusing.

[DerekNonGeneric]

Thanks for the speedy correction! We just need one more approval and we can get this landed.

Thanks!

[DerekNonGeneric]

@VoltrexMaster, if you would be able to ensure that the line length does not exceed 80 characters now, it could improve the odds of getting more approvals with a green CI (Markdown linter is complaining).

[VoltrexKeyva]

@VoltrexMaster, if you would be able to ensure that the line length does not exceed 80 characters now, it could improve the odds of getting more approvals with a green CI (Markdown linter is complaining).

👍 Done (Sometimes I hate linters lol)

[mscdex]

I'd much rather opt for the TypedArray#slice() when referring to the instance method where there is no specific instance/context being discussed, otherwise typedArray.slice(). Including prototype not only makes it unnecessarily wordy IMO but I think it's less useful especially as the JS world moves closer towards the notion of (ES) classes (even if they're just syntactical sugar for prototypes behind the scenes) where prototypes aren't really discussed much.

[VoltrexKeyva]

I'd much rather opt for the TypedArray#slice() when referring to the instance method where there is no specific instance/context being discussed, otherwise typedArray.slice(). Including prototype not only makes it unnecessarily wordy IMO but I think it's less useful especially as the JS world moves closer towards the notion of (ES) classes (even if they're just syntactical sugar for prototypes behind the scenes) where prototypes aren't really discussed much.

The thing is, using # as the notation to reference instance properties/methods can confuse beginners or those who have never seen or encountered this style of referencing, besides that; # is not used in JavaScript except for declaring private properties/methods in classes which is still not how you reference them (e.g. this.#test()), and they're also private which can only be used inside the class itself which the properties/methods referenced here are not private, using # can confuse beginners which the documentation should be as beginner-friendly as possible.

[aduh95]

I wish # notation had caught up more, but I agree it's the right call to use .prototype.:

• in Node.js documentation, buffer.md is the only place where this notation is currently being used. I'm rooting for consistency.
• MDN uses .prototype. notation, I think it makes sense to align with them.
• prototype has a meaning for a reader proficient with ECMAScript, the # notation may seem out-of-place.

IMHO typedArray.slice() would not work here, the text is dealing with the effects of slice methods on a Buffer instance – which is also a TypedArray.

[aduh95]

Landed in 8cb6b5d