RE: ACTION-159: review of API document

Hi. Werner.
Thanks a lot for your valuable comments.

I added inline comments as below.

> -----Original Message-----
> From: public-media-annotation-request@w3.org [mailto:public-media-
> annotation-request@w3.org] On Behalf Of Bailer, Werner
> Sent: Thursday, October 08, 2009 11:28 PM
> To: public-media-annotation@w3.org
> Subject: ACTION-159: review of API document
> 
> 
> Dear all,
> 
> I have reviewed the current draft of the API document. It is acceptable as
> a first draft, giving and outline of what the API will be, but clearly
> there are still many open issues. Here are my comments:
> 
> * Section 1 Introduction
> - I think one or two sentences could be added to the introdcution stating
> that many issues are open and that some of the definitions are provisional.

Agreed about additional sentences. 
But I don't understand about definitions. Could you let me know which definitions are required?

> - The sentence "The initial version of this document is not a final
> version." should be dropped, I think that's obvious.

Agreed.

> - while section 2 says only read access is defined, the introduction still
> says the API defines GET and SET operations

To make clear, I think we can add some editorial note to section 2 like "There are many open issues about SET interfaces, so these interfaces will be covered later...".

> - I'm not sure if section 1.1 and 1.2 should be kept, the prefixes are not
> used in the document, so I think a reference to the ontology document for
> the formats in/out of scope is sufficient.

Agreed.

> 
> * Section 2 API Description
> - It could be useful to put the first paragraph (which is long and could
> be split) into a section called e.g. "design considerations".

Agreed.

> - I suggest to move the WebIDL of the complete API after the description
> of the getters or even into an annex.

It could be one of good candidate. But I think current position is also good to the reader for giving bird's-eye view of our API.
So I would like to discuss later about this issue.

> - as mentioned in my earlier comments to the list, it is not clear to me
> why some getters only return a single value (e.g. title), especially if
> there are qualifiers for subtypes/roles.

Right. I agree we have to make clear this issue for each interface.
Do you want to make clear return value for some interfaces for FPWD?

> - identifier example: I think it would be useful to use an example that is
> different from the locator to make this difference clear.

Agreed.

> - list of role/subtype identifiers: should we add the preliminary
> definitions we have to a section in the API document instead of linking to
> the MAWG wiki?

Agreed. Could you suggest appropriate position of this? :)

> - several property definitions mention resource and explain that it can be
> an abstract concept or an instance. It think we should reference section 2
> of the ontology document in the introduction and drop this explanation
> from each of the property descriptions

Agreed.

> - 2.1.5.2 license / statement attribute: is this really free text?
> Shouldn't this be "creativecommons.org/licenses/by/2.5" in the example?
> 

I am not sure. So I think we can add Editorial note to this clause concerning open issue.

> Minor issues:
> - web is sometimes written with uppercase W and sometimes not
> - in the intro paragraph of 2, change "unStructured" -> "Unstructured"
> - title example (2.1.1.2): could be a bit nicer, e.g. spaces instead of
> dashes
> - 2.1.2.2 return type: Array -> array
> - 2.1.3 I suggest to drop "description" from the title
> - 2.1.7.1/2.1.7.2 there is a space missing between "an array of" and
> "object"
> - section C: the list of members should be updated (e.g. Florian is
> missing, my affiliation is outdated)
> - MPEG-21 reference spells MPGE and the rest is missing
> 

Agreed. Thanks for specific comments :)

Best regards,
Wonsuk


> Best regards,
> Werner
> 
> --------------------------------------------------------------------
>   Werner Bailer
>   Institute of Information Systems
>   JOANNEUM RESEARCH Forschungsgesellschaft mbH
>   Steyrergasse 17, A-8010 Graz, AUSTRIA
> 
>   phone:  +43-316-876-1218               mobile: +43-699-1876-1218
>   web:    http://www.joanneum.at/iis        fax: +43-316-876-1191
>   e-mail: mailto:werner.bailer@joanneum.at
> --------------------------------------------------------------------
> 
>

Received on Monday, 12 October 2009 13:11:52 UTC