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 wrote: > On Thursday, March 22, 2012, Joshua Bell 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 wrote: > >> > >> On Wed, Mar 21, 2012 at 5:28 PM, Robin Berjon > 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 > >> > > > > >
Re: [IndexedDB] ReSpec.js changes appears to have broken the IndexedDB spec
On Thursday, March 22, 2012, Joshua Bell 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 / Jonas > On Wed, Mar 21, 2012 at 6:06 PM, Jonas Sicking wrote: >> >> On Wed, Mar 21, 2012 at 5:28 PM, Robin Berjon 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 >> > >
Re: [IndexedDB] ReSpec.js changes appears to have broken the IndexedDB spec
On Wed, Mar 21, 2012 at 5:28 PM, Robin Berjon 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
Re: [IndexedDB] ReSpec.js changes appears to have broken the IndexedDB spec
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. -- Robin Berjon robineko — hired gun, higher standards http://robineko.com/ @robinberjon
[IndexedDB] ReSpec.js changes appears to have broken the IndexedDB spec
Hi All, 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? / Jonas
