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

Below are some comments about Sections 5. and 5.1 of the 18-Aug-2009  
LCWD of the A&E spec:

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

In general, it seems like Section 5. is more verbose that it needs to  
be.

-Regards, Art Barstow


1. The following statement is an implementation detail that should be  
removed:

[[
A user agent must provide a means to flag a key, and its  
corresponding data, as a protected key.
]]

If a UA can implement 6.4 and its subsections, that should be  
sufficient to cover the gist of the above (and if the assertion above  
is removed, there would not be a need to create a test case for it).

2. The following is more verbose than it needs to be:

[[
A user agent must have the ability to create one ore more unique  
storage areas, one for each origin of a widget.
]]

It should be shortened to:

[[
A user agent must be able to create a unique storage areas for each  
origin of a widget.
]]

(At a minimum, fix the Typo: "one ore more").

3. The following statement doesn't seem necessary given preferences  
is of type Storage; as such, I think it should be removed:

[[
A user agent must have the ability to directly read and write to the  
storage area (i.e., without needing to make use of the [WebStorage]  
specification's Storage interface) and must  have the ability to  
delete a storage area.
]]

4. The use of "arbitrary" doesn't seem appropriate here ("An  
arbitrary limit ..."). If anything needs to be said about this hint  
to a UA, it seems like it should just say "A minimum of 5MB per  
origin of a widget is recommended." There is also a typo at the  
beginning of the assertion - should be "A user agent should limit".

5. In the assertion about author scripts, it appears "... ,but must  
behave ..." should be "... and the user agent must behave ...".

6. The following assertion is another implementation detail that  
should be removed or made non-normative:

[[
A user agent should impose their own implementation-specific limits  
on the length of otherwise unconstrained keys and values of a storage  
area, e.g. to prevent denial of service attacks, to guard against  
running out of memory, or to work around platform-specific limitations.
]]

7. The three MAY assertions ("may expire", "may prompt", "may allow")  
don't really add anything useful to the spec and as such should be  
removed or turned into n on-normative text (we presumably don't want  
to create test cases for these).

8. Section 5.1. The following sentence has a couple of problems:

[[
A protected key is a preference held by the widget preferences  
variable of the configuration defaults table that an author has  
explicitly flagged as "read-only" (denoted by a preference having a  
readonly value set to true).
]]

a. The preferences variable isn't included in the "configuration  
defaults table"

b. "widget preferences variable": this text should be changed to  
"Widget object's preferences attribute" and both "Widget" and  
"preferences" should be embedded in <code> tags.

c. The link between the Widget object's preferences attribute and the  
<preference> elements in the config document should be made clear.

It seems like the first sentence above should be something like:

[[
A protected key is an item in the Widget object's preferences  
attribute that an author has flagged as "read-only" (denoted by a  
<preference> element as defined in [Widgets-Packaging] having a  
readonly value set to true).
]]

Received on Wednesday, 9 September 2009 20:08:24 UTC