Re: Scope of doc changes due to processing model

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.