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

On Thu, Sep 10, 2009 at 8:17 PM, Arthur Barstow <art.barstow@nokia.com> wrote:
> 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?

Well, the problem we have is that we want to imply "window object"
without explicitly saying window object :).  To answer your second
question, it is easy to test in any context:

if(widget instanceof Widget){
   //pass
}

That is, because widget is assumed to be bound to the global scope of
widget, we can test for it's presence without needing to qualify the
object with it's global context (which, normally would be 'window'.).
The problem is that what is meant by the "global object context" is
not defined. We might need to leech some HTML5 terminology to make
this more clear.

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

No, it's a redundant statement of fact. However, it intros the API. I
shrunk it down to:

"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/...]

Changed argument to IRI (shh, hopefully no one will notice!)

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

Made non-normative. I want to keep that text so it's clear that you
can have both localStorage and preferences.

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

Used your text

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

Right, fixed globally.

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

Yes, they are crap. But I'd rather keep them till we come up with better ones.

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

Nice!

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

Ok, I deleted that. The whole storage mutex thing is super confusing
anyway. Hopefully it will be clarified in WebStorage and in HTML5.

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

Right. Updated.


-- 
Marcos Caceres
http://datadriven.com.au

Received on Sunday, 13 September 2009 21:24:32 UTC