Skip to content

Editorial: inconsistent prose for intrinsics #2576

@jmdyck

Description

@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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions