Generic guide to exceptions, events, etc. for new APIs Re: [indexeddb] New WebIDL Exception Model for IndexedDB

On Saturday, 1 October 2011 at 08:15, Anne van Kesteren wrote:

> On Sat, 01 Oct 2011 02:56:55 +0200, Israel Hilerio <israelh@microsoft.com (mailto:israelh@microsoft.com)>  
> wrote:
> > On Friday, September 30, 2011 12:23 AM, Anne van Kesteren wrote:
> > > Actually, given
> > > http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-throw
> > > it does. Which is what I was trying to convey. HTML does this too now:
> > > http://html5.org/r/6602
> >  
> > The DOM 4 spec link you sent us is exactly the approach we’re following  
> > but with a simpler language. Instead of defining what it means to throw  
> > a type as an exception (like you do on DOM 4), we’re following the  
> > WebIDL spec to define the exception type in a simpler fashion. Look at  
> > the note contained in the WebIDL spec under IDL Exceptions where it says  
> > there is no IDL syntax for declaring exception types:
> > http://dev.w3.org/2006/webapi/WebIDL/#idl-exceptions
> >  
> > We believe it is simpler and closer to the intent on the WebIDL spec to  
> > say: Throws a DOMException of type " VersionError".
>  
> It's also wrong, since it does not say what code will be.
>  
>  
> > Instead of having to explain what it means to throw a type as an  
> > exception:
> > To throw a “VersionError” exception, a user agent would construct a  
> > DOMException exception whose type is " VersionError " and code exception  
> > field value is 0, and actually throw that object as an exception.
>  
> It seems you misunderstood DOM4. All you need to say is:
>  
> # Throw a "VersionError" exception
>  
> That is it. The DOM4 definition of "throw" handles the details, such as  
> setting message and code.
This is great! Makes it super easy.  
>  
>  
> > This discussion shows that the review process can catch these types of  
> > issues and reviewers like yourself can make us aware of exceptions we  
> > should reuse. Even if it didn’t, the worst case scenario is that a  
> > developer would have similar Exceptions that have slightly different  
> > types and names. Each name or type should be meaningful enough for the  
> > developer to allow them to disambiguate. The main point is that we  
> > don’t believe we should over engineer a solution to a problem that is  
> > not pervasive at this point.
> >  
> > We could even add a note to the DOM 4 spec that states, "We encourage  
> > the reuse of these exceptions instead of defining new ones. Only define  
> > new ones if the current set of exceptions doesn’t meet your needs."
>  
> I guess I don't really see what you think the problem is with keeping a  
> non-normative table in DOM4 (or elsewhere) listing the exceptions in use.
>  

(generally speaking...)  
Seems there is a lot of confusion about how to do this properly (and I'm seeing that this is going to now be an issue amongst a number of groups, including this group, DAP, and even other organisations that are trying their best to define new APIs such as Webinos and WAC).  

Perhaps the best thing to do would be to create a wiki page that defines how to do this using some very generic examples. What would be great would be to see how the prose maps to the IDL and how the IDL maps to a real object in Java script… and also show how the DOM4 spec takes care of setting the code and the message…. so, a "Exceptions and events for [Spec Writing] Dummies" would be greatly appreciated (and will avoid a few common mistakes).  


--  
Marcos Caceres
http://datadriven.com.au

Received on Sunday, 2 October 2011 11:39:23 UTC