[Contacts] ED feedback

http://dev.w3.org/2009/dap/contacts/#attributes-1


> addresses of type array of ContactAddress, nullable
> This attribute represents one or more physical addresses
> associated with this Contact.

The attribute exists regardless of whether it is null, right? Should it say zero or more? -- This comment applies to all nullable array attributes.

Also, I don't think "represents" is correct, it probably "exposes". -- This comment applies to all attributes claiming to represent things...

Note that later text uses "captures" for the same confusing meaning:

> This attribute captures one or more phone numbers associated with this Contact.

The text should settle on a single phrasing.

> displayName of type DOMString, nullable
> This attribute contains the name of this Contact in a
> form that is suitable for display to the user.

This is a bit nitpicky, if someone sends me a contact card with a displayName of "Дмитрий Медведев", the card I receive isn't invalid, however, for me, that displayName is not suitable. I don't have a great replacement for "suitable for display to the user". I think s/to the user// is probably necessary, possibly s/suitable/preferable/. To use a simpler example, my own card could have a display name of "Josh", but my first name is "Joshua", and both are quite suitable for display to me, as a user, one however is *preferable*.

> An implementation must maintain this globally unique identifier
> when a Contact is added to an address book.

What does this mean? If I have a card "Josh" and I generate a guid for it, and then someone asks me for it, and I give it to them, and then they give me a new card with the same guid and with a name of "Joshua", what is my user agent supposed to do when asked to add it? If the user chooses to create a new card instead of merging the card with the original, then a "must maintain *this* guid" is problematic.

> This attribute should not be used to send down arbitrary
> photos taken by this user, but specifically profile photos
> of the contact suitable for display when describing the contact.

I haven't checked today, but on Facebook, Google Chat, AIM, and most other sites, people often have contact photos which are not specifically "profile[1] photos". On some sites, the content of such a photo could even be "unsuitable for display".

Ignoring that, s/down//; s/describing/showing/

> urls of type array of ContactField, nullable
>    This attribute represents one or more URLs associated with
> this Contact e.g. personal web page, blog.
>    The web resources must be specified using the value attribute
> of the ContactField object, and its type field may be set to "blog"
> or "profile".

I half expect most of these "type" fields to be null or empty most of the time -- except null isn't allowed for the type field which means it'll have to be empty instead. I also worry about how anyone will deal with them when they cross language boundaries, I mean, if I sent you a Contact.urls: [
{type: "博客", value: "http://博客.example.com/博客/me", pref: false},
{type: "блог", value: "http://блог.example.com/блог/me", pref: false},
], what would you do with the type fields?

http://dev.w3.org/2009/dap/contacts/#contactname-interface


> interface ContactName {
>    attribute DOMString? formatted;
>    attribute DOMString? familyName;

http://dev.w3.org/2009/dap/contacts/#attributes-2


> familyName of type DOMString, nullable
> formatted of type DOMString, nullable

Is there any reason that the order of the Attribute definitions doesn't match the order of the interface? If the reason is because formatted is special, then perhaps an extra blank line between it and the rest of the fields would be beneficial.

> formatted of type DOMString, nullable
> This attribute contains the full name, including all the individual
> components such as givenName, middleName, familyName, prefix, suffix as
> appropriate for the user's culture, and formatted for display (e.g. Mr.
> Joe Smith Jr.).

The "as appropriate for the user's culture" requirement might be an unreasonable burden for implementers. If I get a contact card from some other data source, I have no idea if that card was formatted for my user's culture or someone else's. It's formatted certainly, but not necessarily for my user (see earlier example of the Russian President). In many cases the UA does not know the user's culture, and there are certainly many cards whose name content would not fit the culture of the user. I also suspect that there are some cultures which wouldn't include all name elements in a card as part of a full name.

> middleName of type DOMString, nullable
>    This attribute contains the middle name of this Contact.

Having recently had my middle name stored as the first name of two in my last name field, it's worth noting that many of these name fields can arbitrarily have multiple "names" inside them, especially the middleName and familyName fields. -- In my case it was an error (which has since been corrected). But it's definitely possible to have "El ingenioso hidalgo don Quixote de la Mancha"
  possibly: {
title: "El ingenisoso hidalgo", givenName: "don Quixote", familyName: "la Manca", formatted: "El ingenioso hidalgo don Quixote de la Mancha"
}

or "Francisco José de Goya y Lucientes"
  possibly: {
givenName: "Francisco", middleName: "José", familyName: "Goya y Lucientes", formatted: "Francisco José de Goya y Lucientes"}

A number of those smaller words will be shoehorned into random other fields. It's possible that some of those smaller words will not be present in any other fields...

Also suggested was "Maria Luisa Josefina Antonieta Vicenta". (Titles for such people are really amusing.)


http://dev.w3.org/2009/dap/contacts/#advanced-search-qualifiers


> We call composed attributes Contact attributes of types object,

"we call" sounds like a definition of <composed attributes>, which would be ok.

> which contain information only available only through child
> attributes of that object, or array.

But ", or array" is confusing and doesn't seem to fit within the structure of the sentence. I think the problem might simply be an extraneous comma before "or array".

> A requesting application must be able to request both the full

s/fully/fully/ ?

> composed Contact attribute and also be able to request individual

s/also.*request//

> parts of a composed Contact attribute

s/$/./

> in the search qualifier provided to a Contacts find() operation.

This part should be moved to the beginning of the sentence:

The SQ of a Contacts find() operation must allow a requesting application to ...

> Example
> The following Contact search is initiated:
>     navigator.contacts( ['emails.value', 'name', 'friends'],
>                         function(contacts) { 
>                           for(i in contacts) {
>                             for(j in contacts[i].emails)
>                               alert(contacts[i].emails[j]);
>                           }
>                         } );

> The above example logically implies:

> 1. Return only the valid Contact attributes requested in the provided
> search qualifier (name, emails.value - friends is not a valid
> Contact attribute so ignore this element).

I can't figure out which of "name", "emails.value" or "friends" is objectionable according to the parenthetical.

http://dev.w3.org/2009/dap/contacts/#search-filters


> A search filter may be specified from a requesting web
> application to provide a hint to the user agents as to

s/agents/agent/

> which contacts the user can select to share with the
> application.

"can select" is odd, perhaps "which contacts the application would like the user to provide".

> The actual usage of this search filter is user-agent dependant,

s/dependant/dependent/
(you rarely ever want dependant.)

[1] http://www.merriam-webster.com/dictionary/profile?show=0&t=1309803535 : a representation of something in outline; especially : a human head or face represented or seen in a side view

---------------------------------------------------------------------
This transmission (including any attachments) may contain confidential information, privileged material (including material protected by the solicitor-client or other applicable privileges), or constitute non-public information. Any use of this information by anyone other than the intended recipient is prohibited. If you have received this transmission in error, please immediately reply to the sender and delete this information from your system. Use, dissemination, distribution, or reproduction of this transmission by unintended recipients is not authorized and may be unlawful.

Received on Monday, 4 July 2011 19:21:36 UTC