Re: Scope of doc changes due to processing model

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"