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

Hi timeless!

Thank you for taking your time for doing a review on our doc! i have responded inline to every comment.

Cheers.

Am 17.06.2011 um 16:52 schrieb timeless:

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

Changed. Searched the whole document for occurence of "the api".

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

Changed.

> 
>> DOMString mediaResource
>> This attribute must set the specific media resource for which the API applies.
> 
> The "for which...applies" is awkward :(

Changed to "This attribute must set the specific media resource that should be processed by the API.".

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

Not available in the text any more.

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

I would stick to method. Other opinions?

> 
>> Interfaces defining the actual retrieval methods for metadata, called MediaResource, ...
> 
> <ways to retrieve metadata>

Has been rephrased already.

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

Changed.


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

already changed.

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

Fixed.

> 
> 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/ ?

Fixed

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

Done.

>> Other components depict in Figure 1....
> 
> depicted
> 
> 

Done.

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

I think method is correct here.

> 
>> if(noErrorStatus(title[0].statusCode) == true) {
>> if(noErrorStatus(dcMetadata[0].statusCode) == true) {
> 
> Also note that style generally includes a space between 'if' and '(':

Done.

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

_____________________________
Dipl. Inf. Florian Stegmaier
Chair of Distributed Information Systems
University of Passau
Innstr. 43
94032 Passau

Room 248 ITZ

Tel.: +49 851 509 3063
Fax: +49 851 509 3062

stegmai@dimis.fim.uni-passau.de
https://www.dimis.fim.uni-passau.de/iris/
http://twitter.com/fstegmai
_____________________________

Received on Monday, 27 June 2011 12:55:00 UTC