How do we document the semantics of this parameters in methods?

[Josh-Cena]

JS functions have an implicit parameter called this. For example, map is a function that reads every element of this, and puts the mapped elements in a new array.

array.map((i) => i ** 2); // The source elements are read from `array`

Internally, you can see it being implemented as

Array.prototype.map = function map(fn) {
  const another = new (this.constructor[Symbol.species] ?? Array)(this.length);
  for (const i = 0; i < this.length; i++)
    if (i in this) another[i] = fn(this[i], i, this);
  return another;
}

If it's not apparent enough that this is part of the parameters, consider the TypeScript syntax, which makes it apparent that this is a positional parameter:

function map<T, V>(this: T[], fn: (val: T, i: number, arr: T[]) => V): V[] {
  const another: T[] = new (this.constructor[Symbol.species] ?? Array)(this.length);
  for (const i = 0; i < this.length; i++)
    if (i in this) another[i] = fn(this[i], i, this);
  return another;
}
Array.prototype.map = map;

Or the fact that Reflect.apply, which is the reflective semantic of calling a function, takes fn, thisArg, args as its three parameters.

In "normal" cases, the this parameter is the one before the "dot". ("Normal" a.k.a minus Function.prototype.bind et al.) However, in the "Syntax" section, it's written as:

map(fn)

I'd say that's factually wrong, because it's claiming the function can be called without a this at all! If you do that, you get a TypeError, because the this passed to Array.prototype.map is undefined:

const { map } = [1, 2, 3];
map((i) => i ** 2); // TypeError: Array.prototype.map called on null or undefined

Therefore, I think it's immediately apparent that the "host" of the method should be part of the syntax, because without it it would be a TypeError, which is not any better than missing one required parameter.

array.map(fn)

This may have other impacts as well. For example, for Generator.prototype.return(), we are forced to add a generatorObject subject, because return is a keyword and without the subject it's literally invalid syntax.

Therefore, my first question is: Is it worth the effort to add a formal subject to the "Syntax" section? Do we want to have uniform naming conventions in this case (for example, camel-cased constructor name, suffixed with Object/Instance)?

---

I hope it's mostly undisputed that adding a subject to the "Syntax" section is worth it since that's what people write 99.9% of the time anyway. However, do we want to document the semantics of the this parameter (i.e. what does the language expect the value used as this to have, what happens when it's missing, what does the method do to this...)? If so, how?

ECMAScript spec has defined a series of built-in methods that are "intentionally generic", making the this parameter part of the semantics and can be meaningfully customized. For example, to quote Array.p.map:

The map function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

As one can see from the code above, the algorithmic steps of Array.p.map, as it's defined in the spec, only does the following to this:

• Reads this.constructor[Symbol.species] to construct the new Array (falling back to the global Array so this isn't required)
• Iterates through this.length
• Checks if each number index access exists
• Accesses the existing number indexes

Therefore, it can be transferred to any array-like object:

console.log(({ map: Array.prototype.map, 0: 1, 1: 2, 2: 3, length: 3 }).map((i) => i ** 2));

That's such an important aspect of the language that everywhere a method is "intentionally generic", the spec leaves an editorial note. There are 110 such notes in ES2022!

As for some other methods (especially web APIs), there're strict branded checks to make sure the this is of the right type. For example, Map.p.get uses the [[MapData]] internal slot so it can't be used on non-Map instances.

I proposed in mdn/content#17981 that we should add this to the "Parameters" section, in light of the fact that this is indeed part of the parameters. However, there're worries that it unnecessarily bloats the reference pages since most people don't call the method on non-array objects anyway. I'm therefore starting the discussion to discuss how we should document the semantics of this in such a way that:

• We expose the use-cases of customizing this, and the requirements for a valid this. (Does it require an internal slot and therefore can only be called on a particular class? Does it only use certain properties?)
• We do not bloat the sections and make average readers lost.
• Most importantly, we "fully document" the language's behavior, not just how it's used "90% of the time", since that is probably what the majority already know anyway.

Should we:

• Add a uniform > **Note:** similar to that in the spec? (Trivial effort, but without another section to describe the algorithmic steps like what I've done above, the note is basically cryptic for most readers)
• Add an example? (Significant effort, examples are not easy to make)
• Add an entry in the "Parameters" section? (Even more significant effort, requires decent understanding of the spec, may be unuseful for normal readers, but permits fully explaining the nuances)
• Other options?

Prior art: on Array.p.pop and a few others, it's already documented that:

Using an object in an array-like fashion

push and pop are intentionally generic, and we can use that to our advantage — as the following example shows.

However, these remarks are really sporadic and scattered throughout the docs, and we have far more cases where the behavior is not noted.

[OnkarRuikar]

Recently we added page types to all WebAPI pages mdn/content#16255.
It marked all the pages with info regarding static vs property, method vs variable vs constructor. I believe this is planned to be used in page titles e.g. "Notification: requestPermission() static method". [ref]

As it would be apparent from title/heading whether the method is static or member, there won't be need to specify owner objects in syntax sections. And it'll keep the syntax sections concise.
We've updated syntax sections of WebAPI pages recently, e.g. https://github.com/mdn/content/pull/14920/files

This hasn't been done for JS pages yet.

---

We can skip eslinting syntax sections by marking them as jssyntax or jslike.

---

Add an entry in the "Parameters" section? (Even more significant effort, requires decent understanding of the spec, may be unuseful for normal readers, but permits fully explaining the nuances)

It may make the Web Docs sounding like a manual or the language specification itself. 🤔

Add an example? (Significant effort, examples are not easy to make)

We can add specific examples for special cases explaining the scenarios. Contributors can help with the effort if we we make good first issues for these cases.

[bergus]

I think #14857 and following were a mistake.

As it would be apparent from title/heading whether the method is static or member, there won't be need to specify owner objects in syntax sections. And it'll keep the syntax sections concise.

@OnkarRuikar No, the syntax section should show the signature with an example call. And the receiver object is a very important part of it, to distinguish it from a global function. The goal is not conciseness, it's readability; and to a certain amount, copy-paste-ability. Otherwise you could argue that the method name is already in the page title as well, so why not drop that as well? Just refer to the parameters by index and drop the syntax example altogether? That is not good documentation imo.