Enqueue an operation vs queue a task

[soareschen]

Section 3 imports the concept of queue a task from HTML5.

Section 4.3.1.2 defines "Enqueue an operation" which has an operation queue of running one task at a time.

I tried searching through the spec and there are two phrases being used:

1. queue a task that runs the following steps
2. enqueue the following steps

I'd guess that (1) refers to the HTML5 task and (2) refers to the operation queue. If so, the only section that make use of enqueue operation is 4.3.1.6 "Set the RTCSessionSessionDescription".

If that is correct, I think the sections should be better organized to document the use. In particular, place the "Enqueue an operation" side by side with "Set the RTCSessionSessionDescription", and add a note to clarify that the remaining sections refer to the HTML5 task.

Because "Enqueue an operation" is introduced so early and prominently in the spec, I have been wrongly assuming that all tasks are enqueued as operation instead of HTML5 task. :(

[adam-be]

The operations queue is used by createOffer, createAnswer and addIceCandidate as well. In those steps it's referred to as Return the result of enqueuing the following steps. These references are also linked.

[soareschen]

I see. I was searching the word "enqueue" and missed those steps because they use the word "enqueuing".

I feel that the terminology for "enqueue the following steps" need to be more distinguishable from "queue a task". The words "enqueue" vs "queue" look too similar and does not signify that they have fundamentally different semantics.

Perhaps "enqueue the following steps to connection's operation queue" is better fit for the descriptions? It is more easily searchable and also signifies which operation queue that is being enqueued to.

[adam-be]

I think what you're suggesting would be an improvement.

[stefhak]

I'm labeling this issue as editorial based on the discussion above. @soareschen would you be willing to provide a PR for this?

[soareschen]

Yes I can work on this next week. Currently prioritizing on WPT tasks for WebRTC first.