Re: Contacts API: a few comments

Hi Cathy,

Cathy.Chan@nokia.com wrote:
> Hi all,
>
> I have a few comments on the latest draft of the Contacts API (http://dev.w3.org/2009/dap/contacts/).
>
> 1. [small nit] In the example following the Introduction, the Contacts find method was invoked with ['name', 'email'], but the success callback accesses 'displayName', which should not be present in the resulting Contact object. It would be more appropriate and less confusing to use name (or name.formatted) in the success callback instead.

Typo fixed. Example now uses '.name' in the success callback function. 
See [1].

> 2.  [small nit] In 4.3 Contacts Interface (http://dev.w3.org/2009/dap/contacts/#contactname-interface), the note "Each Contact must include either a displayName or the name attribute." which appears under the description of displayName should appear under the description of the name attribute as well.

Added to name attribute section also. See [1].

> 3. [question] 5.1 Search Qualifiers (http://dev.w3.org/2009/dap/contacts/#search-qualifiers) says "If the search qualifier provided is of zero-length then the current Contacts find() operation must not return any Contact properties within any resulting Contact object(s)." Does that mean the success callback would be invoked with one or more Contact objects each with no properties at all? Wouldn't that contradict with the statement that "Each Contact must include either a displayName or the name attribute."?

I agree this is not an ideal situation.

I made a change to the specification in [1] to say that when zero search 
qualifiers are provided, then treat the request as invalid and throw the 
error callback with a code of INVALID_ARGUMENT_ERROR.

> 4. [bug] In 4.8 ContactFindOptions interface (http://dev.w3.org/2009/dap/contacts/#contactfindoptions-interface), the description of the 'multiple' attribute says "By default this option is set to true." But in 5.2 Options Processing (http://dev.w3.org/2009/dap/contacts/#options-processing), it says that "By default, the Contacts find() operation must return either an empty sequence or a single Contact object, accessible as part of the sequence returned in the ContactFindCB callback function", and that the 'multiple' attribute needs to be set to true to retrieve multiple objects. To me, that reads "the attribute is false by default". Which one is correct?

I've made a change to say that the 'multiple' is, by default, 'false' 
and must be set to true to receive zero, one or more Contact objects in 
the success callbacks defined.



Thanks for taking the time to review the specification. Please see the 
CVS log for a summary of the changes as a result of the above discussion 
[1] and let us know if you encounter any other issues in the current spec.

Many thanks,

Rich

[1] 
http://dev.w3.org/cvsweb/2009/dap/contacts/Overview.html.diff?r1=1.128;r2=1.129;f=h

Received on Wednesday, 25 May 2011 11:58:01 UTC