Hi Max, Thanks again for taking the time to perform a detailed review. Addressed all your suggestions. Comments below. Please confirm changes where appropriate.
On Thu, Apr 16, 2009 at 3:49 PM, Max Froumentin <[email protected]> wrote: > A few comments on http://dev.w3.org/2006/waf/widgets-api/Overview.src.html > > 1. [Abstract] "the Widgets 1.0 Family of Specifications" link to section > explaining what the Family is. fixed > 2. [Conformance] "This specification describes the conformance criteria for > user agents [...] and various resource types". What are the various resource > types? Isn't the statement contradictory with "There is only one class of > product that can claim conformance to this specification: a user agent." ? > right, fixed. Deleted mention of additional resources. > 3. [User Agents] "A user agent is an implementation" a bit vague. Perhaps > some of the text in the following note should be move here, to refine the > definition. > I changed it to "A user agent is software that implements the application programming interfaces defined in this specification. A user agent must behave as described by this specification in order to claim conformance." > 4. [User Agents] "widget user agent" link to where the term is defined. Changed all instances of widget user agent to user agent. > 5. [Dependencies on Other Specifications] The last 2 statements logically > yield "A user agent MUST attempt to implement [some specifications]" > now reads: [[ A user agent supports a specification if it attempts to implement that specification. A user agent MUST support: * the [Widgets-Packaging] specification, * the [WebStorage] specification's Storage interface, with the exclusion of the Database interface. * the [DOM3Core] specification. ]] > 6. [Dependencies on Other Specifications] "depend", "rely", "supports", > "attempts to implement"... all a bit confusing. > Ok, "support" is the only term used. > 7. [Global Definitions] provide link to definition of Widget object, and > start file. linked. Changed Global Definitions to Definitions. > 8. [Global Definitions] Widget object -> Widget interface ? (object is > Ecmascript centric) Right, fixed. > 9. [The Widget Interface] "The widget interface" -> The Widget interface Fixed. > 10. [The Widget Interface] MUST should be in red. Fixed. > 11. [The Widget Interface] There should be a link to WebIDL somewhere, for > people not familiar with it > Added: "This specification defines defines APIs using [WebIDL]." to the Introduction section. > 12. [The Widget Interface] Why is it dom::DOMString and not DOMString? Right. Fixed. > 13. [The viewMode Attribute] "Steps for Processing a Widget Resource" direct > link would be useful (also further down) > Linked, > 14. [The authorName Attribute] This is a comment on P&C: <author> is used to > deduce the "author name" property, but in the definition of <author> it's > not specified that the element must contain the author's name. > You can't check that, it's not testable. > 14. [The authorURL Attribute] Shoudl logically be called authorHref Agreed. Changed. > 15. [The openURL() Method] Why couldn't this be generalised to open URI, > including mailto:, tel: and more? > Right: changed it to: "The openURL(url) method takes a valid URI as an argument. When invoked, the url should be opened with the appropriate protocol handler for the given URI. If there is no such protocol handler or urlis not a valid URI, then the user agent must act as if the method was not invoked.." > 16. [The getAttention() Method] Make the last statement explicitly > non-normative (as a note for instance) > Changed the offending text to a note. > 17. [The ShowNotification() Method] "reference to a function" is confusing > (also in onmodechange). I would change to just function > Changed to just function. > 18. [Informative References] The references are in a section (the intro) that > is not marked as informative in the conformance section. > Agreed. But that section will be completed when we go to LC. -- Marcos Caceres http://datadriven.com.au
