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).
]]