RE: Status of API document & vacation information

Dear all,

I've reviewed the API document in order to prepare for LC2 publication, here are my comments:

1. editor list
- Wonsuk's affiliation needs to be updated

2. Abstract
- I think it needs rewriting, as it does not really provide the core information now.
- why does it say "related to media resources on the Web" in the first sentence?
- I would drop the text on interpreting IDL as WebIDL from the abstract

3. Status
- there is a reference to "undefined" and "undefined@w3.org"

4. Structure
- as the examples in 4.2 and 4.3 use the MediaAnnotation interface, I think it would be useful to have section 4.4 directly after 4.1

5. Sec. 1: Introduction
- What does the sentence "This document clearly states that the focus for this API is multimedia services on the Web." mean? I think it should be deleted.

6. Sec. 3: Design consideration
- when referring to the mapping tables, do not say "recommended best practice", as section 5 of the ontology document is normative

7. Sec. 4: API description
- 4.1.1: metadataSources: why does it say "_other_ metadata sources" in the description?
- 4.4., design considerations, 1st and last bullet points: MediaAnnotation should be formatted as code
- 4.5.*: I think the block "if(noErrorStatus( ..."  does not need to be repeated for each property
- 4.5.3.4.2: maximum has an equals sign instead of a colon
- 4.5: The return type is always 200, shouldn't we use the 26x types giving more details?
- 4.7: Looking at the 26x return types in more detail: are they really mutually exclusive? 

8. Sec. 5: Usage examples
- 5.2: format the JSON code in the web service examples as source code

9. Formatting issues
- there are some bullet lists with bullets outside the left margin, e.g. section 3, beginning of section 4
- when printing on A4 paper, fig. 1 is slightly too wide
- when printing, no line breaks are done in text formatted as source code, so make sure that lines are short enough

10. Acknowledgments
- check/update the list, e.g., Martin Höffernig is not listed here
- problem with accented characters in Véronique's and Victor's last names

11. References
- the use cases and requirements doc should not say "work in progress"
- refer to a current version of Media Fragments spec, but do not (yet) say W3C Recommendation

Best regards,
Werner


> -----Original Message-----
> From: public-media-annotation-request@w3.org [mailto:public-media-
> annotation-request@w3.org] On Behalf Of Florian Stegmaier
> Sent: Dienstag, 07. Juni 2011 15:23
> To: public-media-annotation@w3.org
> Subject: Status of API document & vacation information
> 
> Dear all,
> 
> Werner just told me that the current status of the API document was not
> quiet clear to all of you. I have forwarded the last email regarding
> the last changes of the API document. From my point of view (despite
> schema.org discussion today) we have nearly reached the final version.
> The validation of the WebIDL definition was the last thing on my
> editing list. It would be really nice if we could initiate a review
> phase by all group participants. I would propose to have a review round
> until 24th of June. After that we could discuss changes/issues in the
> Teleconf on 28th of June. After that, i could re-edit things an we
> could move on to 2nd LC. I think also the implementations should be in
> a final state until than.
> 
> Personal information: i will be on vacation from 13th of June until the
> 26th of June. Possibly i can respond to important emails, but i cannot
> join Teleconfs. Sorry for that.
> 
> Best,
> Florian
> 
> Anfang der weitergeleiteten E-Mail:
> 
> > Von: Florian Stegmaier <stegmai@dimis.fim.uni-passau.de>
> > Datum: 17. Mai 2011 14:00:42 MESZ
> > An: public-media-annotation@w3.org
> > Betreff: Fwd: WebIDL compatibility test
> >
> > Dear all,
> >
> > just a small update to my last email: I have also deleted the sub-
> module descriptions of the WebIDL specification. These modules have
> been added to improve readability, but current checking tools seem to
> have problems interpreting/resolve them. In order to avoid
> compatibility issues in future, i have removed all sub-modules since
> they did not carry any further information.
> >
> > Some smaller issues with the document were...
> >   ... occurrence of int as datatype (e.g., getSupportedModes)
> >   ... property name conflicts (e.g., status vs. statusCode)
> >
> > From my point of view we reach 2nd LC soon.
> >
> > Cheers,
> > Florian
> >
> > Anfang der weitergeleiteten E-Mail:
> >
> >> Umgeleitet von: public-media-annotation@w3.org
> >> Von: Florian Stegmaier <stegmai@dimis.fim.uni-passau.de>
> >> Datum: 17. Mai 2011 12:58:30 MESZ
> >> An: public-media-annotation@w3.org
> >> Betreff: WebIDL compatibility test
> >>
> >> Dear all,
> >>
> >> Dom was so kind to update the WebIDL checker [1] to the new WebIDL
> spec. He said it is very close to the specification now. I have
> performed a check to the API WebIDL file [2] and got lots of errors. I
> have removed them and now we have a syntactical correct version. It has
> been already updated in the specification (see [3] for diff).
> >>
> >> Cheers,
> >> Florian
> >>
> >> [1] http://www.w3.org/2009/07/webidl-check
> >> [2] http://dev.w3.org/2008/video/mediaann/mediaont-api-1.0/mawg.idl
> >> [3] http://dev.w3.org/cvsweb/2008/video/mediaann/mediaont-api-
> 1.0/mediaont-api-1.0.html.diff?r1=text&tr1=1.112&r2=text&tr2=1.114
> >> _____________________________
> >> 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
> >> https://www.dimis.fim.uni-passau.de/iris/
> >> http://twitter.com/fstegmai
> >> _____________________________
> >
> > _____________________________
> > 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
> > https://www.dimis.fim.uni-passau.de/iris/
> > http://twitter.com/fstegmai
> > _____________________________
> >
> 
> _____________________________
> 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
> https://www.dimis.fim.uni-passau.de/iris/
> http://twitter.com/fstegmai
> _____________________________
>

Received on Wednesday, 8 June 2011 08:46:08 UTC