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.
