RE: ACTION-158: review the API document

Hi. Pierre Antoine.
Most of all, thank you for 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 Pierre-Antoine
> Sent: Saturday, October 10, 2009 1:21 AM
> To: public-media-annotation@w3.org
> Subject: ACTION-158: review the API document
> 
> 
> Dear all,
> 
> I have also reviewed the current draft of the API document. It also lead
> me to re-read the ontology document, on which I also have some comments,
> regarding its relation with the API.
> 
> I think some parts of the Ontology document may belong to the API
> document: the definition of datatypes (Ont:3.1), and the Syntactic Level
> Mapping (Ont:4.2.1.2). 

I am not sure, so it's required further discussion.

> 
> I also think, as Raphaël suggested in a recent telecon, that the
> ontology document should specify the range of its property, but at a
> conceptual level. This would require introducing a few concepts such as
> Agent (for creator/contributor), Duration... Links to existing
> ontologies could be given (reusing their term directly?? maybe).
> 
> Then the API document would specify how those types are *represented*
> for the purpose of the API -- which is done by the various interfaces
> given by the document.
> 
> Other remarks:
> - is the NoValue exception really necessary? Doesn't WebIDL have some
> long of 'null' value?

Sorry, could you explain again about your point?

> - I would suggest that attributs returning a list of objects use the
> plural form; e.g. 'creators' instead of 'creator'

Agreed.

> - I suggest that 'contributor' return a list (hence become 'contributors')

Agreed.

> - I suggest that Language is *required* to comply with RFC4646, or this
> will hinder interoperability.

I agreed with Felix's email.

> - is it ok that the unit for Duration is fixed to 'second'? Can all used
> units be converted exactly to seconds? is a granularity of seconds
> always sufficient for duration?

I will add editorial note for this issue. We can figure out later.

> - is it ok for the bitrate to be a number? What about Variable Bit Rate?
> Or would we raise NoValue in that case? (might be an option... after all
> we dont seek exhaustiveness)

I will also add editorial note for this issue. :)

> - it is not clearly explained what the 'context' of a rating is.

I will also add editorial note for this issue. ;)

> 
> Typos and minor remarks:
> - in the abstract *and* section 1: "provide developers an convenient" ->
> "provide developers with a convenient"
> - in the abstract "Media Ontology Core Properties" should link to the
> ontology document
> - in the secton about License, the interface of the return value is not
> give,
> - in the section about Compression, the given interface is FrameSize

Thanks for specific comments.

> I have other remarks, somehow deeper, but that shouldn't prevent us from
> publishing the first draft, I think.

I would like to get your all of feedbacks later ;)
Thanks.

Best regards,
Wonsuk.

>    pa

Received on Tuesday, 13 October 2009 08:38:23 UTC