Re: Response to your LC Comment -2394 on Media API spec

On Wed, Sep 29, 2010 at 5:54 AM, timeless <timeless@gmail.com> wrote:
> disposition of comments: ok

> I'd like to take the time then to read the document in its current state and ensure the
> text integrated well.

Sorry for the delay, I looked over the current version of the document
/ the changes that were made in response to my comments. It seems like
my comments while generally accepted did not get properly
indicated/integrated in some instances. This is probably my fault for
using shorthands....

For quoting purposes,
'>' is http://dev.w3.org/2008/video/mediaann/mediaont-api-1.0/mediaont-api-1.0.html
'>>' is your reply to my comments ('>>>')
'>>>' is my original comments
'>>>>' is probably what the spec was when I wrote my comments

>>> I'd write "this API" instead of "the API" here and in the rest of this document.
>> [MA] Agreed.

The following instances were not changed. I had hoped by writing "And
in the rest of this document" and that your response of "[MA] Agreed"
that you would also change them:
> These properties will be used as a pivot vocabulary in this API. The API is described in Web IDL

s/The API/This API/ or s/The API/It/ ?

> This API defines/exposes ... Here, interoperability ... The API offers operations to request particular metadata information represented in a certain metadata format related to media resources on the Web.

s/The API/This API/ or s/The API/It/

> Further it specifies the actual representation of the core properties and the API behaviour.

s/the API/their/ ?

> Before introducing .. of the API.... For this API the asynchronous mode is ...

> Figure 1: Two scenarios with different usage of the API.

> Note: This specification defines only the API for Media Resource. Other components depict in Figure 1....

This instance is ok/correct

> Scenario 1: User agent
> In this scenario, the API is implemented ...
> Scenario 2: Web service
> In the second scenario, the API is encapsulated ...
> In both scenarios, the API
> Note that, the API provides access to ...

These are probably best left as is.

> The MediaResource interface is the core of the API and provides

> Further, This operation allows to set the specific media resource and metadata sources to which the API is applied.

I wonder why "This" is capitalized...

> DOMString mediaResource
> This attribute must set the specific media resource for which the API applies.

The "for which...applies" is awkward :(

> The API MUST fill value with a printable string representation
> if a URI identifies a value known by the API, use the appropriate label

Probably s/API/implementation/ for both instances here.

> As such, the API introduces no additional security issue.

s/the API/this API/

>> [MA] "Operation" is the term used in Web IDL to denote "method".

I need to spend more time reading Web IDL :).

Note that you use "method" and "methods" throughout the text of the
specification, I wonder if you should use <Operation(s)> :).

... The Web IDL specification seems to generally reserve "method" for
implementation details and host object/language bindings.

> Interfaces defining the actual retrieval methods for metadata, called MediaResource, ...

<ways to retrieve metadata>

> Next, the different interfaces and exposed methods
> We have not specified exceptions on the methods
> The MediaResource interface ... provides methods to access ...

operations?
or in cases where you don't mean <operations> you might want to use
<means> to avoid the semi-technical term (which Web IDL seems to have
reserved for its own purposes).

> the getMediaProperty() method of AsyncMediaResource or SyncMediaResource interface.

> createMediaResource...
>    This method instantiates ...

operation?

> The getMediaProperty method is part of this interface so the returned element has an implementation of this method.

This sounds circular or something. +method/operation x2

> By calling the getMediaProperty method ...

> MediaAnnotation interface is used as the return type of MediaResource.getMediaProperty method.

> This section ... the MediaResource.getMediaProperty() method.
> When invoking this method
> When the MediaResource.getMediaProperty method
(this appears a bunch of times in different sections)

> syntactical error with respect to the GET method used
> only a subset of GET methods for properties implemented

These are correct (per rfc2616)

> These APIs will provide the methods for requesting metadata information

s/the methods/a means/

>>> I'd request that you consider whether your document
>>> is in fact written in en-US and thus should use "behavior".
>> [MA] Agreed.

> Further it specifies the actual representation of the core properties and the API behaviour.
> iii) API behaviour (e.g., status codes).
> This section introduces a set of status codes for the defined API to indicate the system behavior.
> Changed "behaviour" to "behavior".

Please change the other two instances from "behaviour" to "behavior".

>>>> codes for general informations (e.g., bad request), but also system specific
>>> information

You didn't actually write '[MA]', but the current text has:

> It uses a subset of the HTML/1.1 [[HTTP11]] status codes for general information (e.g., bad request), but also system specific information (e.g., property not defined in source format).

so, it was fixed here, but not here:

> method stubs for accessing the metadata informations

information

The following items are things I saw while checking the integration of
your changes in response to my feedback. They (as noted in my original
DoC) are purely editorial comments.

> Note: This specification defines only the API for Media Resource.

s/defines only/only defines/ ?

Shouldn't it be "Media Resources" (plural)?
If not, you probably need the article 'a' before 'Media'.

> Other components depict in Figure 1....

depicted



This related to the method/Operation item from your response to me,
but I've broken it out since it is its own thing which I didn't raise
originally:

> The noErrorStatus method ensures that no error is

This looks like a function; not a method/operation:

> if(noErrorStatus(title[0].statusCode) == true) {
> if(noErrorStatus(dcMetadata[0].statusCode) == true) {

Also note that style generally includes a space between 'if' and '(':

>     if (noErrorStatus(titles[0].statusCode) == true) {
>            if (titles[j].titleLabel == "Apocalypse Now") {
>                    if (tempResults[i].roleLabel == "director") {

Received on Friday, 17 June 2011 14:52:31 UTC