[webrtc-pc] Terminology around "setting" attributes may be incorrect

taylor-b has just created a new issue for https://github.com/w3c/webrtc-pc:

== Terminology around "setting" attributes may be incorrect ==
In various places, we talk about "setting" attributes. This comes in three flavors:

1. Setting an internal slot, which is read by the attribute's getter. For example:

> Store the configuration in the [[ configuration]] internal slot.

2. Setting some abstract thing, which can be assumed to be an internal slot. For example:

> An RTCPeerConnection object has a **signaling state**, a **connection state**, an **ICE gathering state**, and an **ICE connection state**. These are initialized when the object is created.
> ...
> To update the **ICE gathering state** of an RTCPeerConnection instance _connection_, the user agent must queue a task that runs the following steps:
> ...
> 4. Set _connection_'s **ice gathering state** to newState.

This seems acceptable. Though, for consistency and to be more formal, I'd suggest just describing these things as internal slots as well.

3. Setting the attribute itself. For example:

> Set connection's pendingLocalDescription , currentLocalDescription , pendingRemoteDescription and currentRemoteDescription to null.

In WebIDL terminology, this seems as if it would be formally interpreted as "call the attribute's setter". But it's a readonly attribute, so it doesn't have a setter. Is this ok (since it's obvious enough what the intention was), or should we change these places to use an internal slot as well?

For example, say in the description of `pendingLocalDescription`:

> Returns the value of the `[[pendingLocalDescription]]` internal slot.

And change the above quote to:

> Set connection's `[[pendingLocalDescription]]` , `[[currentLocalDescription]]`, `[[pendingRemoteDescription]]` and `[[currentRemoteDescription]]` internal slots to null.



Please view or discuss this issue at https://github.com/w3c/webrtc-pc/issues/1112 using your GitHub account

Received on Thursday, 6 April 2017 15:52:04 UTC