Re: Generic guide to exceptions, events, etc. for new APIs Re: [indexeddb] New WebIDL Exception Model for IndexedDB
On Monday, October 3, 2011 at 11:43 PM, Arun Ranganathan wrote: (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). I agree, and admit to confusion on my part here as well. I'm keen that errors and exceptions are spec'd consistently across the platform. We're now contemplating eliminating things that we once took for granted (for example, having a dedicated exception such as FileException, etc.). Robin took the initiative to create a skeleton: http://test.w3.org/webapps/api-design/ Maybe we can do a quick breakout session with Anne and anyone else interested during TPAC and fill it in. We just need quick bullet points and Robin and I can add examples etc. Kind regards, Marcos
Re: Generic guide to exceptions, events, etc. for new APIs Re: [indexeddb] New WebIDL Exception Model for IndexedDB
On 10/6/11 12:16 PM, ext Marcos Caceres wrote: On Monday, October 3, 2011 at 11:43 PM, Arun Ranganathan wrote: (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). I agree, and admit to confusion on my part here as well. I'm keen that errors and exceptions are spec'd consistently across the platform. We're now contemplating eliminating things that we once took for granted (for example, having a dedicated exception such as FileException, etc.). Robin took the initiative to create a skeleton: http://test.w3.org/webapps/api-design/ Maybe we can do a quick breakout session with Anne and anyone else interested during TPAC and fill it in. We just need quick bullet points and Robin and I can add examples etc. FYI, I added it to WebApps' Potential Topics list http://www.w3.org/2008/webapps/wiki/TPAC2011#Potential_Topics.
Re: Generic guide to exceptions, events, etc. for new APIs Re: [indexeddb] New WebIDL Exception Model for IndexedDB
On 10/2/11 7:38 AM, Marcos Caceres wrote: On Saturday, 1 October 2011 at 08:15, Anne van Kesteren wrote: On Sat, 01 Oct 2011 02:56:55 +0200, Israel Hilerioisra...@microsoft.com (mailto:isra...@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). I agree, and admit to confusion on my part here as well. I'm keen that errors and exceptions are spec'd consistently across the platform. We're now contemplating eliminating things that we once took for granted (for example, having a dedicated exception such as FileException, etc.). -- A*
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 isra...@microsoft.com (mailto:isra...@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
