Re: review of A&E

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 <maxfro@opera.com> 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

Received on Thursday, 23 April 2009 10:46:29 UTC