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

2010/4/13 Chris Poppe <Chris.Poppe@ugent.be>

>  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 offer*s *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?).
>

Yes, I will work on that, hopefully this week.

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-respec.html
>
>
>
> Best regards,
>
> Wonsuk.
>