doc: <integer> is misleading

[seishun]

📗 API Reference Docs Problem

• Version: master

Location

Affected URL(s):

• https://nodejs.org/api/buffer
• https://nodejs.org/api/events
  ...among others

Problem description

Many methods are documented to take <integer> or <integer[]>. Examples:
Buffer.from(array)
emitter.setMaxListeners(n)
It seems to always mean "an integer Number". However, clicking the type link leads to an MDN section that starts with "ECMAScript has two built-in numeric types: Number and BigInt (see below).". One might erroneously think that BigInt, which is also an "integer", works too.

---

• I would like to work on this issue and submit a pull request.

[DerekNonGeneric]

Any clues on what needs to be done to correct this? It seems as though C++ types are being mixed into the JS docs.

/cc @addaleax

[BridgeAR]

We declare a variable as integer in case it should be an integer, not a decimal number. It's still a number as actual JS type but it should still be useful for the reader to know that we likely validate that it's in fact an integer (or that the API will only work as expected with integers).

We might want to stop referencing to JS numbers on MDN. Besides that, I would keep it as is.

[DerekNonGeneric]

I wonder if it would be more helpful to link to specification in this regard.

https://www.ecma-international.org/ecma-262/6.0/#sec-number.isinteger

[DerekNonGeneric]

I found a nice sentence from the V8 docs supporting my initial thought about them
being C++ integers, so alternatives may exist.

These accessor functions convert a C++ integer to a JavaScript integer using
Integer::New, and convert a JavaScript integer to a C++ integer using
Int32Value. — https://v8.dev/docs/embed#accessing-static-global-variables

Since @BridgeAR gave me the lead on this, it would be nice to have his approval
on #33766 too, but no pressure.

[DerekNonGeneric]

I would have liked to link to something like the following.

https://docs.oracle.com/javase/10/docs/api/java/lang/Integer.html

Unsure if linking to the class from the V8 docs would be out of the question.

https://v8docs.nodesource.com/node-14.1/df/d84/classv8_1_1_integer.html

Or is it too late to create an Integer class, implement it, and document it?

I'm not really sure what needs to be done here… (Sorry I couldn't be of more help on this.)