telepathy-qt: dbus-tubes: Improve comments, and fix a variety of typos

[Dario Freddi]

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

Author: Dario Freddi <dario.freddi at collabora.co.uk>
Date:   Thu Jun  9 16:26:25 2011 +0200

dbus-tubes: Improve comments, and fix a variety of typos

---

 TelepathyQt/dbus-tube-channel.cpp              |   21 +++++++++++++--------
 TelepathyQt/outgoing-dbus-tube-channel.cpp     |    5 +++--
 TelepathyQt/pending-dbus-tube.cpp              |    2 +-
 TelepathyQt/requestable-channel-class-spec.cpp |    2 +-
 4 files changed, 18 insertions(+), 12 deletions(-)

diff --git a/TelepathyQt/dbus-tube-channel.cpp b/TelepathyQt/dbus-tube-channel.cpp
index 927e6a1..66505d7 100644
--- a/TelepathyQt/dbus-tube-channel.cpp
+++ b/TelepathyQt/dbus-tube-channel.cpp
@@ -124,7 +124,7 @@ void DBusTubeChannel::Private::introspectBusNamesMonitoring(DBusTubeChannel::Pri
         parent->connect(dbusTubeInterface, SIGNAL(DBusNamesChanged(Tp::DBusTubeParticipants,Tp::UIntList)),
                         parent, SLOT(onDBusNamesChanged(Tp::DBusTubeParticipants,Tp::UIntList)));
     } else {
-        warning() << "FeatureBusNameMonitoring does not make sense in a P2P context";
+        debug() << "FeatureBusNameMonitoring does not make sense in a P2P context";
     }
 
     self->readinessHelper->setIntrospectCompleted(DBusTubeChannel::FeatureBusNameMonitoring, true);
@@ -234,9 +234,7 @@ DBusTubeChannel::~DBusTubeChannel()
 }
 
 /**
- * Returns the service name which will be used over the tube. This should be a
- * well-known and valid DBus service name, in the form "org.domain.service". Tubes
- * providing invalid service names might cause non-predictable behavior.
+ * Returns the service name which will be used over the tube.
  *
  * This method requires DBusTubeChannel::FeatureDBusTube to be enabled.
  *
@@ -292,7 +290,7 @@ bool DBusTubeChannel::supportsCredentials() const
 }
 
 /**
- * If the tube has been opened, this function returns the private bus address you should be listening
+ * If the tube has been opened, this function returns the private bus address you should be connecting
  * to for using this tube.
  *
  * Please note this function will return a meaningful value only if the tube has already
@@ -313,9 +311,12 @@ QString DBusTubeChannel::address() const
 }
 
 /**
- * This function returns all the known active connections since FeatureConnectionMonitoring has
+ * This function returns all the known active connections since FeatureBusNameMonitoring has
  * been enabled. For this method to return all known connections, you need to make
- * FeatureConnectionMonitoring ready before accepting or offering the tube.
+ * FeatureBusNameMonitoring ready before accepting or offering the tube.
+ *
+ * This function will always return an empty hash in case the tube is p2p, even if
+ * FeatureBusNameMonitoring has been activated.
  *
  * \returns A list of active connection ids known to this tube
  */
@@ -407,7 +408,11 @@ void DBusTubeChannel::setAddress(const QString& address)
 /**
  * \fn void DBusTubeChannel::busNamesChanged(const QHash< ContactPtr, QString > &added, const QList< ContactPtr > &removed)
  *
- * Emitted when the participants of this tube change
+ * 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.
  *
  * \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/outgoing-dbus-tube-channel.cpp b/TelepathyQt/outgoing-dbus-tube-channel.cpp
index 09a2b6a..de32dc9 100644
--- a/TelepathyQt/outgoing-dbus-tube-channel.cpp
+++ b/TelepathyQt/outgoing-dbus-tube-channel.cpp
@@ -157,13 +157,14 @@ OutgoingDBusTubeChannel::~OutgoingDBusTubeChannel()
 /**
  * Offer the tube
  *
- * This method creates a brand new private DBus connection, and offers it through the tube.
+ * This method sets up a private DBus connection to the channel target(s), and offers it through the tube.
  *
  * The %PendingDBusTube returned by this method will be completed as soon as the tube is
  * opened and ready to be used.
  *
  * \param parameters A dictionary of arbitrary Parameters to send with the tube offer.
- *                   Please read the specification for more details.
+ *                   The other end will receive this QVariantMap in the parameters() method
+ *                   of the corresponding IncomingStreamTubeChannel.
  * \param requireCredentials Whether the server should require an SCM_CREDENTIALS message
  *                           upon connection.
  *
diff --git a/TelepathyQt/pending-dbus-tube.cpp b/TelepathyQt/pending-dbus-tube.cpp
index 0d597af..b7b3ff7 100644
--- a/TelepathyQt/pending-dbus-tube.cpp
+++ b/TelepathyQt/pending-dbus-tube.cpp
@@ -180,7 +180,7 @@ void PendingDBusTube::onStateChanged(TubeChannelState state)
 {
     debug() << "Tube state changed to " << state;
     if (state == TubeChannelStateOpen) {
-        // The tube is ready: let's inject the address into the tube itself
+        // The tube is ready: mark the operation as finished
         setFinished();
     } else if (state != TubeChannelStateLocalPending) {
         // Something happened
diff --git a/TelepathyQt/requestable-channel-class-spec.cpp b/TelepathyQt/requestable-channel-class-spec.cpp
index 0b6c519..3073f0b 100644
--- a/TelepathyQt/requestable-channel-class-spec.cpp
+++ b/TelepathyQt/requestable-channel-class-spec.cpp
@@ -439,7 +439,7 @@ RequestableChannelClassSpec RequestableChannelClassSpec::dbusTube(const QString
     if (!spec.isValid()) {
         RequestableChannelClass rcc;
         rcc.fixedProperties.insert(TP_QT_IFACE_CHANNEL + QLatin1String(".ChannelType"),
-                TP_QT_IFACE_CHANNEL_TYPE_STREAM_TUBE);
+                TP_QT_IFACE_CHANNEL_TYPE_DBUS_TUBE);
         rcc.fixedProperties.insert(TP_QT_IFACE_CHANNEL + QLatin1String(".TargetHandleType"),
                 (uint) HandleTypeContact);
         spec = RequestableChannelClassSpec(rcc);