Scope of doc changes due to processing model

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.

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).

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.


.            .       .    .  . ...Joe

*Joe Berkovitz*

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

Received on Thursday, 8 October 2015 19:24:29 UTC