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

Hi. Chris.

Thanks for your comments.

 

I added inline comments as below.

 

From: Chris Poppe [mailto:Chris.Poppe@ugent.be] 
Sent: Tuesday, April 13, 2010 6:49 PM
To: 이원석; 'Florian Stegmaier'; public-media-annotation@w3.org
Subject: 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.

è  Which browser do you use ? If you use the chrome or firefox browser. You can look at all of thing you said.

                                                                                                                               

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

è  Yes. we can use the id attribute for link.

 

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

è  It’s also related with the browser dependency. So try again with chrome or firefox. It will work.

 

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

è  Right.

 

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.

è  Agreed.

 

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

è  Yes. It should be added.

 

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

è  Right. When I prepared this version, I couldn’t find the good position for these information you mentioned. So you can propose ;)

 

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.

è  Yes. I agreed. We have to illustrate more clear examples in the whole of API doc.

 

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

è  Yes. For most of editing to API doc, we need to edit the HTML source file. For editing references, we need to biblio.js file.

è  You can get the further information from the below link [1] regarding to the new editing tool.

[1]  http://dev.w3.org/2009/dap/ReSpec.js/documentation.html


 

Best regards,

Wonsuk.

 

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


 

Best regards,

Wonsuk.