What I also want is a defined variable name for the value passed to setters that I can refer back to. I usually use something like "the given value" but that's not really exact. It needs to be something that IDL passes in.

I thought about this a bit and how it would be best to define this. I think it would make the most sense if IDL derived the algorithm it has to invoke from the interface/class and then invokes it with a set of parameters.

So e.g.

  interface SomeClass {
    boolean someMethod();
  }

ends up generating an algorithm name SomeClassSomeMethod that IDL invokes with "this" as the first argument and in this case no other arguments since someMethod() takes none. The specification that defines this interface would define the SomeClassSomeMethod algorithm.

That gets us much closer to a formal way of defining APIs. For getter/setter properties you'd obviously have two such algorithms, the latter passed a value argument along with "this". Note that for getter/setter we could also generate default algorithms, once bug 27354 is fixed, so that specifications only need to define these algorithms if something more complex happens than getting and setting an internal slot.

(And then further in the future IDL could standardize the metalanguage used in these algorithms, such as "return", "continue", loops, etc. Which will hopefully make specifications more readable than they are now.)

I certainly see the attractiveness of this for spec writers. If more of the boilerplate can be automated, that's pretty good.

On the other hand, this might lead to the level of formalism of creating a new spec programming language with full syntax validation, which might restrict the freedom of prose in algorithms, thus making it trickier to write "correct" specs, and serving as even more of a barrier-of-entry for new spec writers.

Ideally specifications aligning on style lowers the barrier to copy-and-paste patterns (which is how most new specification writers start out).

I think the style described in comment 2 is rather ambitious and is kind of a separate bug from formalizing the ambient values available.

Regarding the original request, I think we have two concrete things to solve these days (realms are in a better place due to other work):

- a "this value" of some sort, which is an IDL object (not a JS object)
- a "given value" for setters, which is an IDL object (not a JS object)

---

I'd propose we make the "this value" ambient and the "given value" explicit, so algorithms are written like:

The `foo()` method `Bar` objects performs these steps:

1. Let _qux_ be **this**.[[qux]].
1. Let _realm_ be the <a>relevant Realm</a> of **this**.
1. Return 5.

The `baz` attribute of `Bar` objects, on setting to _value_, performs these steps:

1. Set **this**.[[baz]] to _value_.

(Typographical note: **this** could, in HTML, end up being <b>this</b>, or maybe <code>this</code>. Semantically it should not be <emu-val>this</emu-val> since it is an IDL value instead of an ECMAScript value---even though, for objects, the distinction is fairly pointless.)

---

To handle this, we'll need to edit the following sections, in my estimation:

- https://heycam.github.io/webidl/#idl-operations should get updated to talk about how the description of the operation may use the ambient value **this**.
- https://heycam.github.io/webidl/#dfn-create-operation-function step 2.6 should be updated from "on _O_ if _O_ is not **null**" to something like "with the ambient value **this** set to _O_, if _O_ is not **null**."
- https://heycam.github.io/webidl/#idl-attributes should talk about how attributes have "on getting" and "on setting" steps, and how "on setting" steps accept a single argument which is an IDL value.
- https://heycam.github.io/webidl/#dfn-attribute-getter and https://heycam.github.io/webidl/#dfn-attribute-setter should be updated to refer back to that definition of "on getting"/"on setting", and in the case of the setter, explicitly pass in _idlValue_.

Also, it may help to start a new top-level section, say, "Writing Web IDL-Using Specs" or some better name. It would contain examples of these patterns, like my above "so algorithms are written like". The main purpose is to make people aware of the magic sentences you should use when introducing operation steps/attribute getters/attribute setters. Although maybe these should just be incorporated into the #idl-operations and #idl-attributes sections instead for now, and eventually when we get enough material we could pull it out into something top-level.

> even though, for objects, the distinction is fairly pointless.

It's not entirely pointless, because given browser extension APIs the mapping from the IDL value to the ES value is more or less one-to-many....  This means that anything that wants to manipulate the ES value may need to consider saying _which_ ES value.