telepathy-qt: dbus-tubes: Fix comments

[Dario Freddi]

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

Author: Dario Freddi <dario.freddi at collabora.co.uk>
Date:   Tue Jun 14 14:49:21 2011 +0200

dbus-tubes: Fix comments

---

 TelepathyQt/contact-capabilities.cpp       |    4 ++--
 TelepathyQt/dbus-tube-channel.cpp          |    3 +--
 TelepathyQt/incoming-dbus-tube-channel.cpp |   20 ++++++--------------
 TelepathyQt/outgoing-dbus-tube-channel.cpp |   20 ++++++--------------
 4 files changed, 15 insertions(+), 32 deletions(-)

diff --git a/TelepathyQt/contact-capabilities.cpp b/TelepathyQt/contact-capabilities.cpp
index 4709d1c..21d5266 100644
--- a/TelepathyQt/contact-capabilities.cpp
+++ b/TelepathyQt/contact-capabilities.cpp
@@ -84,8 +84,8 @@ ContactCapabilities::~ContactCapabilities()
 }
 
 /**
- * Return whether creating a DBusTube channel, using the given \a serviceName, by providing a
- * contact identifier is supported.
+ * Returns whether creating a DBusTube channel with the given service targeting this contact is
+ * expected to succeed.
  *
  * \return \c true if supported, \c false otherwise.
  */
diff --git a/TelepathyQt/dbus-tube-channel.cpp b/TelepathyQt/dbus-tube-channel.cpp
index 01eb919..952c871 100644
--- a/TelepathyQt/dbus-tube-channel.cpp
+++ b/TelepathyQt/dbus-tube-channel.cpp
@@ -415,8 +415,7 @@ void DBusTubeChannel::setAddress(const QString& address)
  * Emitted when the participants of this tube change.
  *
  * This signal will be emitted only if the tube is a group tube (not p2p), and if the
- * FeatureBusNameMonitoring feature has been enabled. You usually want to wait until the
- * aforementioned feature is ready before connecting to this signal.
+ * FeatureBusNameMonitoring feature has been enabled.
  *
  * \param added An hash containing the contacts who joined this tube, with their respective bus name.
  * \param removed A list containing the contacts who left this tube.
diff --git a/TelepathyQt/incoming-dbus-tube-channel.cpp b/TelepathyQt/incoming-dbus-tube-channel.cpp
index c2ac22b..d84bf90 100644
--- a/TelepathyQt/incoming-dbus-tube-channel.cpp
+++ b/TelepathyQt/incoming-dbus-tube-channel.cpp
@@ -107,17 +107,11 @@ IncomingDBusTubeChannel::Private::~Private()
  * are ready. In this case, we need to enable TubeChannel::FeatureTube and
  * DBusTubeChannel::FeatureDBusTube.
  *
- * \code
- *
- * Features features = Features() << TubeChannel::FeatureTube
- *                                << DBusTubeChannel::FeatureDBusTube;
- * connect(myTube->becomeReady(features),
- *         SIGNAL(finished(Tp::PendingOperation *)),
- *         SLOT(onDBusTubeChannelReady(Tp::PendingOperation *)));
- *
- * \endcode
- *
- * To learn more on how to use introspectable and features, please see \ref account_ready_sec.
+ * DBusTubeChannel features can be enabled by constructing a ChannelFactory and enabling the desired features,
+ * and passing it to ChannelRequest or ClientRegistrar when creating them as appropriate. However,
+ * if a particular feature is only ever used in a specific circumstance, such as an user opening
+ * some settings dialog separate from the general view of the application, features can be later
+ * enabled as needed by calling becomeReady().
  *
  * Once your object is ready, you can use #acceptTube to accept the tube and create a brand
  * new private DBus connection.
@@ -134,7 +128,7 @@ IncomingDBusTubeChannel::Private::~Private()
  *     }
  *
  *     QString address = op->address();
- *     // Do some stuff here
+ *     // Connect to the address
  * }
  * \endcode
  *
@@ -194,8 +188,6 @@ IncomingDBusTubeChannel::~IncomingDBusTubeChannel()
  *
  * This method requires DBusTubeChannel::FeatureDBusTube to be enabled.
  *
- * \note When using QHostAddress::Any, the allowedPort parameter is ignored.
- *
  * \param requireCredentials Whether the server should require an SCM_CREDENTIALS message
  *                           upon connection.
  *
diff --git a/TelepathyQt/outgoing-dbus-tube-channel.cpp b/TelepathyQt/outgoing-dbus-tube-channel.cpp
index de32dc9..3504919 100644
--- a/TelepathyQt/outgoing-dbus-tube-channel.cpp
+++ b/TelepathyQt/outgoing-dbus-tube-channel.cpp
@@ -80,25 +80,17 @@ OutgoingDBusTubeChannel::Private::~Private()
  * PendingChannelRequest *tube = myaccount->createDBusTube(myfriend, "org.my.service");
  * \endcode
  *
- * Be sure to track the pending request to retrieve your outgoing DBus tube upon success.
- *
  * \subsection outgoing_dbus_tube_offer_sec Offering the tube
  *
  * Before being ready to offer the tube, we must be sure the required features on our object
  * are ready. In this case, we need to enable TubeChannel::FeatureTube
- * and StreamTubeChannel::FeatureDBusTube.
- *
- * \code
- *
- * Features features = Features() << TubeChannel::FeatureTube
- *                                << DBusTubeChannel::FeatureDBusTube;
- * connect(myTube->becomeReady(features),
- *         SIGNAL(finished(Tp::PendingOperation *)),
- *         SLOT(onDBusTubeChannelReady(Tp::PendingOperation *)));
- *
- * \endcode
+ * and DBusTubeChannel::FeatureDBusTube.
  *
- * To learn more on how to use introspectable and features, please see \ref account_ready_sec.
+ * DBusTubeChannel features can be enabled by constructing a ChannelFactory and enabling the desired features,
+ * and passing it to ChannelRequest or ClientRegistrar when creating them as appropriate. However,
+ * if a particular feature is only ever used in a specific circumstance, such as an user opening
+ * some settings dialog separate from the general view of the application, features can be later
+ * enabled as needed by calling becomeReady().
  *
  * You can also enable DBusTubeChannel::FeatureBusNameMonitoring to monitor connections
  * to the tube.