RE: ACTION-230 Convert the API document to html+script format

Dear all,

 

Here are my comments on the new API document:

 

I am missing version information, editors, abstract, status , table of
contents.

 

Is it possible to include internal linking with this system? (links to the
specific interfaces or methods).

 

Some links are not working ([[WEBIDL]], [[!MEDIA-ANNOT-REQS]], . ) in the
introduction section.

 

MediaResource interface offer access to.  should be offers access to.

 

For me it is not clear what arguments belong to an operation, (for instance
the setContext() operation has two arguments: mediaResource and
metadataSources).

maybe an appropriate subtitle (arguments) would make this more clear.

 

It seems that the return types of the operations are not explained in the
new version (e.g., the Boolean that is returned by setContext()).

 

I am missing some information that glues the different interfaces together.
In the previous version, this was incorporated in text (e.g. see the last
paragraph of the beginning of section 2.3 in [1]).

 

The examples of the services should be updated as well (Felix?). I believe
Sylvia also mentioned this, in fact we return objects with attributes, while
the service examples only return arrays of strings.

For instance for the identifier property, we give back an object implanting
the Identifier interface, so it has two attributes  (value and type):

{value:"ISAN 0000-3BAB-9352-0000-G-0000-0000-Q", type:"ISAN"}

This should be reflected in the JSON format also.

 

Finally, so for making changes we just change the source of the html file?

 

 

 

[1]
http://dev.w3.org/2008/video/mediaann/mediaont-api-1.0/mediaont-api-1.0.html


 

 

Kind regards,

Chris

 

 

From: public-media-annotation-request@w3.org
[mailto:public-media-annotation-request@w3.org] On Behalf Of ???
Sent: maandag 12 april 2010 12:01
To: Chris Poppe; Florian Stegmaier; public-media-annotation@w3.org
Subject: ACTION-230 Convert the API document to html+script format

 

Hi. Co-Editors and All.

Concerning the ACTION-230, I made the converted draft [1] for API doc. For
this version you have to use the chrome browser. (so far I don't know why
the firefox has some problem. I will check.)

I made the new file with different name for converted version. Because after
conformed, I would like to replace the XMLSpec version with this one.

For this work, I added new directory like a "mediaann/ReSpec.js/" in the dev
space.

 

For using the ReSpec tool, I revised the API doc in overall as below

- move the 3. Examples of how to use the API section to the 1.1 Usage
examples section

- move the 2.1 Design consideration section to 2. Design consideration
section

- revise the overall structure of API description section because of the
description style of the ReSpect tool. 

- add conformance section to the section 4. It's should be revised.

- etc.

 

Note: the Reference part will be revised later. 

 

Please review the converted doc. Any comments is more than welcome.

I hope it's better than old one for developers ;)

 

[1]
http://dev.w3.org/2008/video/mediaann/mediaont-api-1.0/mediaont-api-1.0-resp
ec.html

 

Best regards,

Wonsuk.