[Telepathy-commits] [telepathy-qt4/master] Document that the values returned by Connection::status(reason)? might have changed by the time readinessChanged() is emitted

[Olli Salli]

---
 TelepathyQt4/cli-connection.h |   15 +++++++++++----
 1 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/TelepathyQt4/cli-connection.h b/TelepathyQt4/cli-connection.h
index 076bf65..4f2a7d1 100644
--- a/TelepathyQt4/cli-connection.h
+++ b/TelepathyQt4/cli-connection.h
@@ -180,9 +180,13 @@ public:
     Readiness readiness() const;
 
     /**
-     * Returns the connection's status. The returned status is undefined if the
-     * object has readiness #ReadinessJustCreated, but valid in all the other
-     * states.
+     * Returns the connection's status.
+     *
+     * The readiness states correspond to a particular connection status plus
+     * completing the introspection process for that status. Hence the value
+     * returned might have changed by the time readinessChanged() is emitted.
+     * However, with readiness #ReadinessJustCreated no status queries have yet
+     * been made, so the returned value is undefined in this state.
      *
      * \return The status, as defined in #ConnectionStatus.
      */
@@ -190,7 +194,10 @@ public:
 
     /**
      * Returns the reason for the connection's status (which is returned by
-     * status()). The validity rules are the same as for status().
+     * status()). The validity rules are the same as for status(). Because the
+     * returned value signifies the reason for the value returned by status(),
+     * it might also have changed by the time readinessChanged() is
+     * emitted.
      *
      * \return The reason, as defined in #ConnectionStatusReason.
      */
-- 
1.5.6.5