telepathy-qt: Contact: Complete client-types documentation

[Dario Freddi]

Module: telepathy-qt
Branch: master
Commit: 213910763aa2d3d6b4906b61ed2cf9caa3635f41
URL:    http://cgit.freedesktop.org/telepathy/telepathy-qt/commit/?id=213910763aa2d3d6b4906b61ed2cf9caa3635f41

Author: George Kiagiadakis <george.kiagiadakis at collabora.com>
Date:   Thu Jul  5 14:41:11 2012 +0300

Contact: Complete client-types documentation

---

 TelepathyQt/contact.cpp |   36 +++++++++++++++++++++++++++++++-----
 1 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/TelepathyQt/contact.cpp b/TelepathyQt/contact.cpp
index d33b0a2..8f28061 100644
--- a/TelepathyQt/contact.cpp
+++ b/TelepathyQt/contact.cpp
@@ -304,7 +304,7 @@ const Feature Contact::FeatureAddresses = Feature(QLatin1String(Contact::staticM
 /**
  * Feature used in order to access contact client types info.
  *
- * \sa clientTypes(), clientTypesChanged()
+ * \sa clientTypes(), requestClientTypes(), clientTypesChanged()
  */
 const Feature Contact::FeatureClientTypes = Feature(QLatin1String(Contact::staticMetaObject.className()), 9, false);
 
@@ -931,14 +931,19 @@ PendingOperation *Contact::removeFromGroup(const QString &group)
 /**
  * Return the client types of this contact, if known.
  *
- * Client types are represented using the values documented by the XMPP registrar, with some additional
- * types. A contact can set one or more client types, or can simply advertise itself as unknown - in this
- * case, an empty list is returned.
+ * Client types are represented using the values documented by the XMPP registrar,
+ * with some additional types. A contact can set one or more client types, or can simply
+ * advertise itself as unknown - in this case, an empty list is returned.
+ *
+ * This method returns cached information and is more appropriate for "lazy"
+ * client type finding, for instance displaying the client types (if available)
+ * of everyone in your contact list. For getting latest up-to-date information from
+ * the server you should use requestClientTypes() instead.
  *
  * This method requires FeatureClientTypes to be ready.
  *
  * \return A list of the client types advertised by this contact.
- * \sa requestClientTypes, clientTypesUpdated
+ * \sa requestClientTypes(), clientTypesChanged()
  */
 QStringList Contact::clientTypes() const
 {
@@ -952,6 +957,18 @@ QStringList Contact::clientTypes() const
 }
 
 /**
+ * Return the current client types of the given contact.
+ *
+ * If necessary, this method will make a request to the server for up-to-date
+ * information and wait for a reply. Therefore, this method is more appropriate
+ * for use in a "Contact Information..." dialog; it can be used to show progress
+ * information (while waiting for the method to return), and can distinguish
+ * between various error conditions.
+ *
+ * This method requires FeatureClientTypes to be ready.
+ *
+ * \return A list of the client types advertised by this contact.
+ * \sa clientTypes(), clientTypesChanged()
  */
 PendingStringList *Contact::requestClientTypes()
 {
@@ -1412,4 +1429,13 @@ void Contact::setRemovedFromGroup(const QString &group)
  * \sa groups(), addedToGroup()
  */
 
+/**
+ * \fn void Contact::clientTypesChanged(const QStringList &clientTypes)
+ *
+ * Emitted when the client types of this contact change or become known.
+ *
+ * \param clientTypes The contact's client types
+ * \sa clientTypes(), requestClientTypes()
+ */
+
 } // Tp