[Bug 32609] TpContact should have properties to know subscribe/publish state

[bugzilla-daemon at freedesktop.org]

https://bugs.freedesktop.org/show_bug.cgi?id=32609

--- Comment #8 from Simon McVittie <simon.mcvittie at collabora.co.uk> 2011-01-18 07:05:17 PST ---
The API looks fine. Drive-by documentation nits:

> + *  #TpContact:publish-state and #TpContact:publish-request. Require a
> + *  Connection implementing ContactList interface.

... Requires a Connection implementing the
%TP_IFACE_CONNECTION_INTERFACE_CONTACT_LIST interface.

The use of @self as the argument name in tp_contact_get_subscribe_state(),
tp_contact_get_publish_state() and tp_contact_get_publish_request() meant I had
to read the documentation at least twice, due to confusion with the other
meaning of "self" (SelfHandle, etc.).

Replacing "@self" with "this contact" or even "this remote contact" in the text
of the doc-comment would improve it, I think - an exception to the usual rule
that more cross-references make documentation better :-)

Perhaps saying "the local user" instead of "the user" in these docstrings would
also be a good way to disambiguate how our jargon works.

> +   * A #TpSubscriptionState indicating the state of the user's subscription
> +   * to contact's presence.

English grammar: "subscription to this contact's presence" (i.e. add "this")

> +   * A #TpSubscriptionState indicating the state of contact's subscription to
> +   * the user's presence.

English grammar: "the state of this contact's subscription" (i.e. add "this")

-- 
Configure bugmail: https://bugs.freedesktop.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug.