Editorial: inconsistent prose for intrinsics

[jmdyck]

I'm looking at making the prose for intrinsics more consistent. (PR #2575 is a start.)

There are many points of inconsistency. Here are a few to start with.

(1) (a) How should the spec refer to a built-in function within its defining clause?

• by its full 'path' (e.g. "The Object.assign function")
• by just its final property name (e.g., "The assign function")
• in a generic way (e.g. "This function")

[(b) Later: Similarly, how should we refer to a property of an intrinsic?]

(c) Also, sometimes these say "function" and sometimes "method", and I don't think there's a rule that governs which is used. E.g., Object.freeze is "the freeze function", but in the next clause, Object.fromEntries is "the fromEntries method".

(2) Sometimes the preamble re-states the heading's parameter list, sometimes it doesn't.

Personally, I suggest dropping the parameter list in the preamble.

• It doesn't add anything.
• It's an opportunity to make a mistake.
• It can be a bit misleading.

Re the last point, wording such
When the `foo` function is called with arguments _x_ and _y_, the following steps are taken:
suggests that it might be called in some other way, with some other behavior. Whereas
When the `foo` function is called, the following steps are taken:
doesn't have that problem.

[ljharb]

To me, either they’re all functions, or the only methods are the ones that look at the receiver.

[jmdyck]

To me, either they’re all functions,

That would make it easy.

or the only methods are the ones that look at the receiver.

I.e., the ones that reference *this* value?

[ljharb]

Yes.

[bakkot]

Also, sometimes these say "function" and sometimes "method", and I don't think there's a rule that governs which is used.

I think we're already mostly consistent with the rule @ljharb gives, with a few exceptions. Or, almost but not quite equivalently, we could say that anything on a prototype is "method", and anything else is a "function".

The exceptions fall into a few categories, at a quick glance.

• there's a few one-offs like Object.fromEntries (which was probably my fault) and Array.isArray
• whenever we say something is "intentionally not generic" it's described as a "function" rather than a "method" in that prose (which honestly seems backwards), even if not elsewhere
• all the Math.whatever things are described as methods, which was introduced Editorial: define Math functions using algorithm steps #2122 without anyone really thinking about it
• {Typed,}Array.from and{Typed,}Array.of are "method"s, which are kind of a special case in that they are not on a prototype but do look at their receiver (on the other hand, so do Promise.resolve and Promise.reject, and those are still described as "function"s).

[ljharb]

I think that the Promise statics should be described as methods, along with the from/of's; the Maths should be functions; and "intentionally non-generic" should have no impact on the classification.

[jmdyck]

"intentionally non-generic" should have no impact on the classification.

I'm pretty sure @bakkot wasn't saying it should, rather that it was the occasion of anomalies in the status quo.

Specifically, the current spec has 26 occurrences of "not generic" and 56 of "intentionally generic", and in all but 3 cases, the subject is referred to as a "function", even though in many (most?) cases the preamble referred to it as a "method".

[jmdyck]

Note that 4.4.37 defines "method" as "function that is the value of a property", which includes just about every intrinsic function. So that definition should probably change.

[jmdyck]

I think the merge of #2592 can close this. The only thing this issue brought up that that PR didn't handle was the definition of "method", which I've captured in issue #2846.