Re: Scope of doc changes due to processing model

Thanks. And I'm not hating on the hourglass any more!

...Joe "Former Hourglass Hater" Berkovitz

On Fri, Oct 9, 2015 at 8:29 AM, Paul Adenot <padenot@mozilla.com> wrote:

> 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"
>>
>
>


-- 
.            .       .    .  . ...Joe

*Joe Berkovitz*
President

*Noteflight LLC*
49R Day Street / Somerville, MA 02144 / USA
phone: +1 978 314 6271
www.noteflight.com
"Your music, everywhere"