review of A&E

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.
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." ?
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.
4. [User Agents] "widget user agent" link to where the term is defined.
5. [Dependencies on Other Specifications] The last 2 statements logically yield "A user agent MUST attempt to implement [some specifications]"
6. [Dependencies on Other Specifications] "depend", "rely", "supports", "attempts to implement"... all a bit confusing.
7. [Global Definitions] provide link to definition of Widget object, and start file.
8. [Global Definitions] Widget object -> Widget interface ? (object is Ecmascript centric)
9. [The Widget Interface] "The widget interface" -> The Widget interface
10. [The Widget Interface] MUST should be in red.
11. [The Widget Interface]  There should be a link to WebIDL somewhere, for people not familiar with it
12. [The Widget Interface] Why is it dom::DOMString and not DOMString?
13. [The viewMode Attribute] "Steps for Processing a Widget Resource" direct link would be useful (also further down)
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.
14. [The authorURL Attribute] Shoudl logically be called authorHref
15. [The openURL() Method] Why couldn't this be generalised to open URI, including mailto:, tel: and more?
16. [The getAttention() Method] Make the last statement explicitely non-normatice (as a note for instance)
17. [The ShowNotification() Method] "reference to a function" is confusing (also in onmodechange). I would change to just function
18. [Informative References] The references are in a section (the intro) that is not marked as informative in the conformance section.

Max.

Received on Thursday, 16 April 2009 13:50:09 UTC