Editorial: standardizing preambles for concrete methods and internal methods

[jmdyck]

As a follow-up to PR #1914 etc, I'm thinking about standardizing the preambles for concrete methods and internal methods, and I'm looking for some editorial direction.

Concrete methods and internal methods are similar in that the method's target is not named in the method's parameter list, so must be named elsewhere.

For concrete methods, the target-alias is always declared in an algorithm step (typically the algorithm's first), e.g.:

1. Let _envRec_ be the global Environment Record for which the method was invoked.

or

1. Let _module_ be this Cyclic Module Record.

For internal methods, it's usually done in the preamble, e.g.

When the [[DefineOwnProperty]] internal method of an Array exotic object _A_ is called ...

or

The [[Call]] internal method for an ECMAScript function object _F_ is called with ...

but there are also a few cases where it's done in an algorithm step, e.g.:

1. Let _args_ be the arguments object.

Given that, I wonder if you have any preferences for:

• where the target-alias is introduced (preamble vs algorithm step vs somewhere else)?
• the wording by which it is introduced?
• the wording of the preamble (if that's not covered by the previous)?

[michaelficarra]

I prefer it in the preamble, with wording like

When the [[DefineOwnProperty]] internal method of an Array exotic object A is called ...

[jmdyck]

One thing about that wording is that it doesn't parallel the standard wording for abstract operations, i.e.:

The abstract operation (name) takes (arguments) and returns (return-type). (Other description.) It performs the following steps when called:

so it's unclear what the ellipsis represents. E.g., were you thinking this?:

When the (name) (concrete|internal) method of (target-type) (target-alias) is called with (arguments), it returns (return-type). (Other description.) It performs the following steps when called:

If so, we could eliminate the repeated "when [it is] called" and move closer to the standard form for abstract operations with something like:

The (name) (concrete|internal) method of (target-type) (target-alias) takes (arguments) and returns (return-type). (Other description.) It performs the following steps when called:

[michaelficarra]

E.g., were you thinking this?:

Indeed, I was thinking of that kind of wording, but I am okay with either of the two options you listed. I guess the latter is a little nice because it's more similar to the AO preamble wording.

[bakkot]

The (name) (concrete|internal) method of (target-type) (target-alias) takes (arguments) and returns (return-type). (Other description.) It performs the following steps when called:

Editor group talked about it and is in favor of this form. (Except I'm not entirely sure what "target-alias" would look like here; can you give a concrete example?)

[michaelficarra]

@bakkot It's _A_ in

When the [[DefineOwnProperty]] internal method of an Array exotic object _A_ is called ...

[bakkot]

So, concretely,

The [[DefineOwnProperty]] internal method of an Array exotic object A takes arguments P (a property key) and Desc (a Property Descriptor) and returns a Completion Record. It performs the following steps when called: