Re: [IndexedDB] ReSpec.js changes appears to have broken the IndexedDB spec

(For those who are confused, I sent my reply from the wrong account so the
copy to the list was eaten by the list filter. Jonas quoted everything I
wrote, though, so no context is lost.)

On Thu, Mar 22, 2012 at 9:55 AM, Jonas Sicking <jonas@sicking.cc> wrote:

> On Thursday, March 22, 2012, Joshua Bell <jsbell@google.com> wrote:
> > FWIW, I've fielded many questions from developers who were confused by
> those exception tables. The tables imply that as you're debugging code and
> are looking at a caught exception that you can infer everything you need to
> know by looking it up by type in the table. But the table text is not
> specific enough to really diagnose the issue, since (at least in the case
> of methods) it speaks in generalities rather than the specific steps that
> led to the exception being thrown.
> > The algorithmic steps that outline when an exception is thrown are
> somewhat less obvious (i.e. you have to find the exception and work
> backwards through the algorithm to determine which condition was hit at
> what step) but the result is far more precise.
> > This applies more to method calls with multiple steps than attributes
> that either raise or return a value depending on state checks.
>
> Are you referring to the general Exceptions table here:
>
> http://www.w3.org/TR/IndexedDB/#exceptions
>
> Or to the tables after each function that we had before the respec change,
> for example here
>
>
> http://www.w3.org/TR/IndexedDB/#widl-IDBDatabase-transaction-IDBTransaction-any-storeNames-unsigned-short-mode
>

The latter - the tables after each function. Even on a per-function basis,
I've had developers see the table and not read the description in
detail. Some bugs have been filed against the spec and fixed to tighten up
the wording and keep the tables and text in sync, which is good. But if
those tables after each function are gone forever and the exceptions must
be described only in the main text, then IMHO it would be an improvement in
the readability and rigor of the spec.


/ Jonas
>
>
> > On Wed, Mar 21, 2012 at 6:06 PM, Jonas Sicking <jonas@sicking.cc> wrote:
> >>
> >> On Wed, Mar 21, 2012 at 5:28 PM, Robin Berjon <robin@robineko.com>
> wrote:
> >> > Hi Jonas,
> >> >
> >> > On Mar 22, 2012, at 03:41 , Jonas Sicking wrote:
> >> >> It appears that something has changed in respec which causes
> IndexedDB
> >> >> to no longer show the "Exceptions" section for all functions and
> >> >> attributes. IndexedDB relies on the text in the Exceptions section to
> >> >> define a lot of normative requirements which means that the spec
> >> >> currently is very ambiguous in many areas.
> >> >>
> >> >> Robin, was this an intentional change in respec? Is there an old
> >> >> version of the script anywhere that we can link to?
> >> >
> >> > Yes, this was announced to spec-prod (but presumably not everyone
> reads that...):
> >> >
> >> >    http://lists.w3.org/Archives/Public/spec-prod/2012JanMar/0018.html
> >> >
> >> > The problem is basically that "raises" is no longer in WebIDL so I
> had to eventually pull it too lest I generate invalid WebIDL.
> >> >
> >> > There isn't an old version but since this is CVS presumably there's
> some kind of arcane syntax that makes it possible to get it. Perhaps more
> usefully, I'd be happy to figure out a way to still express that
> information but without ties to deprecated WebIDL constructs (preferably
> requiring minimal spec changes).
> >> >
> >> > Sorry about that, I was hoping that people would either a) have moved
> on from old WebIDL syntax, b) see the announcement on spec-prod, or c)
> notice the change and scream immediately. Suggestions for a better protocol
> to handle this sort of change (it's the first of its kind, but possibly not
> the last) are much welcome.
> >>
> >> Simply displaying a table of exceptions after the parameters list
> >> seems like it would be WebIDL compatible. I.e. we wouldn't need the
> >> 'raises' syntax inside the IDL itself, but having a separate
> >> description of the various exceptions thrown by a function seems like
> >> it could be useful.
> >>
> >> Possibly have less focus on the Exception interface-type since it's
> >> almost always going to be DOMException.
> >>
> >> / Jonas
> >>
> >
> >
>