RE: Status of the API Doc v1.0

Dear all,

 

I have  been thinking a bit on the API-document, more specifically on the content. As I see it, it would make more sense to put section 4 (API description) before section 3 (Data type description). Hence the document would have following structure (I also give a brief description of each section as how I would see the API document):

 

1.       Abstract

2.       Introduction: reason why we want to provide an API and an explanation on who should use/implement it.

3.       API description: a precise description of the actual methods in the API, (so these are the methods that can be found in the Strawman API design [1]), described using web IDL. Victor has already sent an excellent example (using IDL). This section needs to define and explain all aspects of those methods (parameters and return values). 

4.       Data type description: Here we discuss for each property in the ontology what the specific return values are.  (for example if we call the GetStructuredValue method for property ma:creator, what would be the structure and content of the result (so in fact a kind of Javadoc style)). The examples that were added to the summary table [2] are an obvious starting point and should also be repeated in this section to clarify what is meant.

5.       Examples of how to use the API: Here I think we should discuss actual (working) implementations that implement this API. 

 

Not everything has been decided upon (which methods, return values, etc. ). However, the document will be a good (imo better) starting point for further discussions on this topic. I also believe that it might be difficult to use the paper that is currently being written as a first version of the API doc. Presumably, only the introduction can benefit from the paper but the contents of the paper is actually more on the ontology and ways to define the mappings.

 

I would happily volunteer in sections 3 and 4 but I would like to go through the web IDL specification first.

 

 

[1] http://www.w3.org/2008/WebVideo/Annotations/wiki/Strawman_API_design_and_notes

[2] http://www.w3.org/2008/WebVideo/Annotations/drafts/ontology10/WD/summary.html 

 

Kind regards,

Chris

 

 

 

From: public-media-annotation-request@w3.org [mailto:public-media-annotation-request@w3.org] On Behalf Of ???
Sent: dinsdag 1 september 2009 4:27
To: Florian Stegmaier; Victor Rodriguez Doncel; Chris Poppe
Cc: public-media-annotation@w3.org; ???
Subject: RE: Status of the API Doc v1.0

 

Dear Florian and All,

We are just in the starting point for preparing API doc because of vacation season.

So, It’s time to hardly work for reaching to our goal. ;) I think we have to make early version of first draft until 15th September.

 

Below is the structure we had and I describe proposal how to describe each part. If anyone have better ideas, please let me know.

In addition, I am looking for volunteers for each part. Please let me know.

 

0.     abstract à need to make first draft

1.     Introduction à need to make first draft

2.     Terminology à firstly add the terms from ontology doc if we need. And then add additional terms if we need.

3.     Data type Description à Do anyone have ideas ?

4.     API Description à After referred Strawman API design and notes page[1] in wiki, describe draft APIs based on the core properties of ontology doc.

5.     Examples of how to use the API(in Java for example(chris), web IDL) à I think it could be covered later after mature of APIs.

 

[1] http://www.w3.org/2008/WebVideo/Annotations/wiki/Strawman_API_design_and_notes

 

 

Best regards,

Wonsuk

 

From: Florian Stegmaier [mailto:stegmai@dimis.fim.uni-passau.de] 
Sent: Monday, August 31, 2009 11:33 PM
To: 이원석; Victor Rodriguez Doncel; Chris Poppe
Cc: public-media-annotation@w3.org
Subject: Status of the API Doc v1.0

 

Dear all!

 

I wanted to know, if there is already a progress on the API Doc v1.0?

 

Should we start working on the outline proposal of Wonsuk? Who will be in charge of coordination and the yet defined parts?

 

I think we should keep in mind, that the first deadline is preety near (early October) and we should initiate the work on it asap.

 

Best,

Florian


_____________________________

Dipl. Inf. Florian Stegmaier
Chair of Distributed Information Systems
University of Passau
Innstr. 43
94032 Passau

Room 248 ITZ
Tel.: +49 851 509 3063
Fax: +49 851 509 3062
stegmai@dimis.fim.uni-passau.de <mailto:hoelblin@fim.uni-passau.de> 

_____________________________

Quote of the week: Computer. This is a Class-A compulsory directive. Compute, to the last digit, the value of pi. (Spock)