diff options
| author | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2013-01-07 18:20:06 +0000 |
|---|---|---|
| committer | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2013-01-08 12:12:08 +0000 |
| commit | fa2f7d914b1525545dd09b38e2919801fa9cd66e (patch) | |
| tree | 6c57b5d441a0425f33987fce045d923d6424ca50 | |
| parent | 8a6535c1c238108fc8173e2337ca0c7d000d32e4 (diff) | |
TpContact: clarify documentation of Names stuff
| -rw-r--r-- | telepathy-glib/contact.c | 28 |
1 files changed, 22 insertions, 6 deletions
diff --git a/telepathy-glib/contact.c b/telepathy-glib/contact.c index 5531bb048..128babff3 100644 --- a/telepathy-glib/contact.c +++ b/telepathy-glib/contact.c @@ -422,7 +422,13 @@ tp_contact_get_alias (TpContact *self) * is re-entered; if the caller requires a string that will persist for * longer than that, it must be copied with g_strdup(). * - * Returns: the same as the #TpContact:nickname + * If the returned value is %NULL, Telepathy user interfaces should be + * prepared to fall back to tp_contact_get_identifier(). + * + * This nickname is supplied by the contact themselves, so it does not + * necessarily unambiguously identify the contact. + * + * Returns: the same as the #TpContact:nickname, possibly %NULL * * Since: 0.UNRELEASED */ @@ -442,7 +448,11 @@ tp_contact_get_nickname (TpContact *self) * is re-entered; if the caller requires a string that will persist for * longer than that, it must be copied with g_strdup(). * - * Returns: the same as the #TpContact:local-alias + * If the returned value is %NULL, Telepathy user interfaces should be + * prepared to fall back to tp_contact_get_identifier(). + * + * This local alias is supplied by the local user, it is suitable for use as a + * main "display name" for the contact. * * Since: 0.UNRELEASED */ @@ -1183,8 +1193,11 @@ tp_contact_class_init (TpContactClass *klass) * This nickname is supplied by the contact themselves, so it does not * necessarily unambiguously identify the contact. * - * On legacy Connection Managers (not implementing Names interface) this - * property will stay as %NULL. + * If the returned value is %NULL, Telepathy user interfaces should be + * prepared to fall back to tp_contact_get_identifier(). This may happen + * if the contact has not provided a nickname for themselves, retrieving + * it was not successful, or the connection manager does not implement + * the Names interface. */ param_spec = g_param_spec_string ("nickname", "Nickname", @@ -1202,8 +1215,11 @@ tp_contact_class_init (TpContactClass *klass) * This local alias is supplied by the local user, it is suitable for use as a * main "display name" for the contact. * - * On legacy Connection Managers (not implementing Names interface) this - * property will stay as %NULL. + * If the returned value is %NULL, Telepathy user interfaces should be + * prepared to fall back to tp_contact_get_identifier(). This may happen + * if the user has not provided an alias for this contact, retrieving + * it was not successful or has not finished yet, or the connection + * manager does not implement the Names interface. */ param_spec = g_param_spec_string ("local-alias", "Local alias", |