[Bug 36881] Wrong documentation for Tp::Account::connectionStatusChanged (and a bunch of other parts of the API)

[bugzilla-daemon at freedesktop.org]

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

--- Comment #3 from Olli Salli <ollisal at gmail.com> 2011-05-31 12:36:06 PDT ---
- * Return whether the information for this contact has been received
+ * Return whether the information for this contact has been received.

"information" might be a bit too broad word to use here. Say "info card" or
"VCard info" or something?

+ * Start a request that the local user stops receiving presence from this
contact.

"request for the local user to stop receiving". Same for the sending part.

+ * Start a request that the local user's presence is sent to this contact
+ * (i.e. that this contact publish attribute becomes
Contact::PresenceStateYes).

This rather authorizes their request to see our presence. We can't force
anybody to see our presence, a capability which the current description
implies.

+ * Start a request to block/unblock this contact (i.e. whether this contact
stops receiving presence
+ * from the local user while blocked).

Besides being long for the short description, the sentence in the parentheses
is incorrect. What blocking means is protocol-dependent; usually it means at
least that they can't send you messages, and try to add you to their contact
list. That sentence would be more appropriate for removing from publish.

(Also: bah, I didn't remember we have this bool block = true API here in
contact as well. We deprecated it in ContactManager in favor of a clearer
blockContacts()/unblockContacts() API. Should have done the same here. Could
you add a FIXME please?).

+ * This signal is emitted when this contact is added to the contact list \a
group.

A bit awkward, perhaps "added to \a group of the contact list". Same for the
removal signal.

+ * emit a signal \link Tp::PendingOperation::finished() \endlink when the
operation

emit the signal

+ * Additionally Telepathy-Qt4 introduces a concept model in which object
features need

no, not a concept model, just a concept :P

Otherwise the async model changes look good, giving our docs a very important
improvement.

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