-
Notifications
You must be signed in to change notification settings - Fork 1.4k
Description
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.