[widgets] Comments on Section 6 of the 18-Aug-2009 LCWD of A&E spec

Below are some comments about Sections 6. (and its sub-sections) of  
the 18-Aug-2009 LCWD of the A&E spec:

  <http://www.w3.org/TR/2009/WD-widgets-apis-20090818/>

-Regards, Art Barstow


1. I don't understand the statement:

[[
A user agent must implement the Widget interface as a widget  
attribute in the global object context of the widget's start file.
]]

What does this mean, in particular what is the "global object context  
of the widget's start file"? How will this assertion be tested?

2. Is the preface "Within the widget context," in the following  
statement necessary:

[[
Within the widget context, the Widget object provides the following  
attributes and methods.
]]

3. Given the type of the openURL method's argument is an IRI, perhaps  
the name of the argument in the interface definition should be  
changed from "uri" to "iri". [Just a suggestion; please, no holy war  
about URLs/URIs/IRIs/...]

4. Delete the following optional functionality or make it non- 
normative since it is just a note to implemtors and functionality we  
don't want to have to test:

[[
A user agent may support the Storage interface on DOM attributes  
other than the preferences attribute (e.g., a user agent can to  
support the [WebStorage] specification's localStorage attribute of  
the window object in conjunction to preferences attribute defined in  
this specification).
]]

5. Section 6.1 - the following statement has some typos/bugs that  
make it a bit difficult to understand:

[[
Upon initialization, a user agent must set the attributes identified  
in the left column of the configuration attributes table to the  
values that correspond in the [Widgets-Packaging]'s the configuration  
defaults table, as identified by the right hand column.
]]

It appears it should be:

[[
Upon initialization of the object, a user agent must set the  
attributes identified in the left column of the configuration  
attributes table to the values that correspond to the Table of  
Configuration Defaults as defined in [Widgets-Packaging] (identified  
by the values in the right hand column).
]]

Additionally, to better match the P&C spec, the title of the right- 
hand column should be "Values in Table of Configuration Defaults".

6. Sections 6.2 and 6.3 - the examples are a bit too contrived to be  
useful. I would delete them both or at least one of them.

7. Section 6.4 - the following would be easier to understand:

[[
A user agent must not fire a storage event, described in  
[WebStorage], if calling the setItem() or removeItem() causes a  
NO_MODIFICATION_ALLOWED_ERR  exception to be thrown.
]]

If it were changed to:

[[
If calling setItem() or removeItem() causes a  
NO_MODIFICATION_ALLOWED_ERR exception, a user agent must not fire a  
storage event (described in [WebStorage]).
]]

8. Section 6.4 and the mutex - given Section 5.1's uniqueness  
requirement of the storage area is the text about the mutex needed?  
If something does indeed need to be said, rather than enumerating the  
two task lists, perhaps it would be better to defer directly to  
[WebStorage] or to customize the following text:

[[
http://dev.w3.org/html5/webstorage/  [[ 3-Sep-2009 version ]]

Whenever the properties of a localStorage attribute's Storage object  
are to be examined, returned, set, or deleted, whether as part of a  
direct property access, when checking for the presence of a property,  
during property enumeration, when determining the number of  
properties present, or as part of the execution of any of the methods  
or attributes defined on the Storage interface. the user agent must  
first obtain the storage mutex.
]]

Additionally, the spec says "... the user agent must obtain the  
storage mutex in manner specified in the [WebStorage] specification:"  
but [WebStorage] doesn't actually say how to obtain the storage mutex  
(rightfully so).

9. Section 6.4.1 - given the group's decision about the following issue:

  Preference element is underspecified
  http://lists.w3.org/Archives/Public/public-webapps/2009JulSep/ 
1032.html

Step #3 must be updated. The example is now wrong and should be deleted.

Received on Thursday, 10 September 2009 18:18:25 UTC