RE: review Proposed Recommendation version of the API for Media Resources 1.0

Hi Thierry, all,

Here are Martin's and my proposed changes after reviewing the document.

Section 3
- second bullet point at beginning: "as a client accessing a Web Service"
- in the paragraph after the two bullet points: drop ", and accessing the metadata sources"
- Fig. 1: should we color the arrows corresponding to the API to highlight them?
- Scenario 1:  change title to "Client-only (User agent)"
- in the scenario 1 paragraph
  - remove quotation marks around API for ...
  - last sentence: full stop after retrievable, drop while, start with "The access ..."
- scenario 2 text
  - replace "encapsulated in" with "implemented as"
  - replace 2 occurrences of "could" with "can"
- paragraph after scenarios: "this API" -> "the API"

Section 4
- 3 bullet points at the beginning: for the first two, add "A " before interface, for all 3 change "interfaces" to "interface"
- 2nd bullet point: add "and its specializations" at the end
- paragraph after bullet points (starting with next)
  - drop "(in case of the MediaResource interfaces and its implementing interfaces)"
  - "support interfaces " -> "support the interfaces"
  - "can be accessed" -> "provided via a callback function"
- last paragraph before 4.1: should the must here be a MUST ?
- 4.1
  - add "(derived from MediaResource)" after " defining two implementing interfaces "
  - add the sentence "  The mediaResource argument identifies the media resource, for which the implementation of this API should try to find relevant metadata sources. Optionally, references to metadata sources can be passed using an array of objects, each implementing the MetadataSource interface (see Section 4.6). "
- 4.2 drop the sentence "  The mediaResource argument identifies the media resource, for which the implementation of this API should try to find relevant metadata sources. Optionally, references to metadata sources can be passed using an array of objects, each implementing the MetadataSource interface. This interface holds an URI identifying the metadata source (metadataSource) and the name of the actual metadata format (sourceFormat). "(this is in the factory method, not in the constructor of this class)
- 4.2.1 / getMediaProperty
  - in the description of propertyNames drop "Optional arguments allow refining the request"
  - in the description of successCallback, MediaAnnotation should be marked up as interface name
  - in the description of sourceFormat: "the corresponding" -> "the specified"
- 4.2.1 / getOriginalMetadata
  - in the description of sourceFormat: "the corresponding" -> "the specified"
- 4.3
  - drop "The MediaResource defines a constructor that can be called to construct the object based on an identifier of the media resource and optionally some metadata sources. The mediaResource argument identifies the media resource, for which the implementation of this API should try to find relevant metadata sources. Optionally, references to metadata sources can be passed using an array of objects, each implementing the MetadataSource interface. This interface holds two attributes, namely an URI identifying the metadata source (metadataSource) and the name of the actual metadata format (sourceFormat). An example, how to create this object can be found here. " (this is in the factory method, not in the constructor of this class)
- 4.3.1 / getMediaProperty
  - in the description of sourceFormat: "the corresponding" -> "the specified"
- 4.3.1 / getOriginalMetadata
  - in the description of sourceFormat: "the corresponding" -> "the specified"
  - "implement a different subtypes" -> "implement different subtypes" 
- 4.4
  - drop the part "enabling an iteration over a set of different properties."
  - replace properties with "metadata properties"
  - "As several properties are complex types" -> "As several properties are defined as complex types"
  - "added these properties with the appropriate types" -> "adding their specific attributes"
  - "specifying the derived types" -> "specifying the derived interfaces"
  - "For all properties," -> "For each property,"
  - "This approach possibly duplicates in value a string that is found in another attribute." -> "This approach possibly duplicates a string that is found in another attribute in the value attribute."
  - " This is considered an acceptable " -> " This is considered as an acceptable "
  - " For consistency, this approach is also followed if the property has only a single attribute. " -> " For consistency, this approach is also followed if the attribute has only either URI or string as type. "
- 4.4.2 note: " - only the implementing subtypes will be created " -> "- only instances of the derived interfaces will be created."
- 4.5 " and the respective attribute of the return value " -> " and the respective attribute of the MediaAnnotation interface (or specialized type) "
- 4.5 note: " genereal " -> " general "
- 4.5.*.1: " value of the propertyName parameter " -> " value of the propertyNames  parameter "
- 4.5.2.3: "avoid naming conflicts is possible in" -> "avoid naming conflicts with other objects named "Date" in"
- 4.5.2.3.1: "represents date" -> "represents a date"
- 4.5.2.4.1: remove "(default is WGS84)" from altitude, latitude, longitude, and add to coordinateSystemLink/Label
- 4.6.2 the variable in the example should be called metadataSource as it holds only a single source
- 4.7
  - MediaAnnotation should be marked up
  - drop " returned by a method call to the API "
- 5.2 drop the comma in " Note that, Web IDL "

Section 6
- "Implementation-Notes" -> "Implementation Notes"
- I couldn't find a statement whether this section is normative or not, thus I'm also wondering whether SHOULD is not marked up in this section on purpose
- intro sentence: add "as well as for interoperability of implementations"
- 6.1
  - heading: " fragements " -> "fragments"
  - owl:sameAs should also be marked up as code
  - " of a fragment with multiple are made " -> " of a fragment with multiple identifiers are made "
- 6.2 " after it is last used " -> "after it has been last used"
- 6.3 
  - " In same cases, interoperability between these modes is desired, for example to access a Web Service by asynchronous calls. " -> " In this context, interoperability between these modes would be a desired feature in order to provide both processing modes based on the implementation of one mode only."
  - markup interface names


Best regards,
Werner

> -----Original Message-----
> From: Thierry MICHEL [mailto:tmichel@w3.org]
> Sent: Mittwoch, 26. Juni 2013 10:27
> To: public-media-annotation@w3.org
> Subject: review Proposed Recommendation version of the API for Media Resources
> 1.0
> 
> All,
> 
> Here is the Proposed Recommendation version of the API for Media Resources 1.0
> 
> https://www.w3.org/2008/WebVideo/Annotations/drafts/API10/PR2/

> 
> Please review carefully this document.
> 
> This will be the last review before going to final Recommendation.
> 
> Thanks for you help.
> 
> Best,
> 
> Thierry
>

Received on Tuesday, 9 July 2013 11:37:19 UTC