Re: Scope of doc changes due to processing model

I agree with you here. It's probably better, as you note in your example
with this `disconnect(AudioNode)` method, to use a relaxed prose when there
is not a lot of "paths" the code could take. When the code cannot throw, or
when there is only a pattern like this:

> [hourglass] When executing this method, follow these steps:
> - If parameter1 is out of range, throw IndexSizeError, and abort these
>   steps
> - If parameter2 is out of range, throw IndexSizeError, and abort these
> steps
> - Send a control message to the rendering thread to execute operation X
>
> Executing operation X on the rendering thread means:
> - .....

could be simply written:

> ([hourglass] when either parameter1 or parameter2 are out of range, throw
> IndexSizeError), else do X.

Note that the hourglass thing applies to a inline element (and if you hover
it, it shows the sentence it applies to), so it's very clear what is
synchronous and what is not.

So in most case, we can have very light markup that is still precise and
unambiguous.

Paul.




On Fri, Oct 9, 2015 at 2:15 PM, Joe Berkovitz <joe@noteflight.com> wrote:

> Thanks, Paul -- I appreciate your explaining this in more detail. I wasn't
> thinking that the "blanket statement" would cover cases where there are
> substantial sync and async components to an operation, such as suspend()
> and I totally get the need to be explict there. I was more thinking of
> cases like AudioNode.disconnect(), as an example. Ultimately, do you feel
> we should change the single sentence, "Disconnects all outgoing connections
> from AudioNode." to...
>
> [hourglass] When executing this method, follow these steps:
> - Send a control message to start processing.
>
> Sending a control message to start processing means executing the
> following steps:
> - Disconnect all outgoing connections from AudioNode
>
>
> I don't personally favor this level of verbosity but I guess it's not
> harmful. I agree this question doesn't have high priority relative to
> clarifying other things and just wanted to push it on the stack of things
> to consider.
>
> ...Joe
>
>
> On Fri, Oct 9, 2015 at 5:28 AM, Paul Adenot <padenot@mozilla.com> wrote:
>
>> On Thu, Oct 8, 2015 at 9:23 PM, Joe Berkovitz <joe@noteflight.com> wrote:
>>
>>> Hi Paul et al,
>>>
>>> I'm wondering (just for my edification) how far you feel we should go in
>>> adjusting the existing documentation for various methods/actions. In
>>> particular, I'm thinking of operations that do not have any synchronous
>>> aspects other than throwing exceptions.
>>>
>>
>> The markup there is _very_ lightweight, and it's already mostly done.
>>
>>
>>>
>>> Would we change all methods today described simply as "...does X" to
>>> say, "...sends a control message that does X when executed on the rendering
>>> thread"? Would we change all descriptions of throwing exceptions to add the
>>> little hourglass icon? (which by the way I find a little confusing, but
>>> maybe that's just me).
>>>
>>
>> The hourglass thing is standard WHATWG notation, I just used the same.
>>
>>
>>> My opinion FWIW is that we should have some kind of blanket statement to
>>> the effect that unless otherwise stated, 1) all documentation of operations
>>> is to be interpreted as a description of the asynchronous effect of the
>>> operation's control message when applied in the control thread, and 2) all
>>> exceptions are thrown in the control thread. Or something clearer than that
>>> :-) Then we can leave most existing descriptions alone.
>>>
>>
>> That would work, but we have a number of things that are way too implicit
>> for a normative text. We also have to annotate all synchronous operations
>> that are not as easy as throwing exceptions (we don't have a lot of this
>> kind of operations but still).
>>
>> As a general direction, I'd rather go with a very explicit style than
>> merely describe what should happen (see the old vs. the new description for
>> `suspend`). Being very explicit about things is how it's done in big specs,
>> and it solves quite a lot of problems.
>>
>> That said, we already have three (or four, depending how you consider
>> lineage) implementations that managed to get it done, so I'd rather
>> prioritize fixing clear bugs (spec compressor and audioworker for starters).
>>
>> Paul.
>>
>>
>
>
> --
> .            .       .    .  . ...Joe
>
> *Joe Berkovitz*
> President
>
> *Noteflight LLC*
> 49R Day Street / Somerville, MA 02144 / USA
> phone: +1 978 314 6271
> www.noteflight.com
> "Your music, everywhere"
>