Document the purpose of outstanding_channels

diff --git a/libempathy/empathy-dispatcher.c b/libempathy/empathy-dispatcher.c
index f46d15f808d6562e212ca0b6756690cf40ca1f3e..0f9cc7746e6f839933974d851f0bc92dcdb12571 100644 (file)
--- a/libempathy/empathy-dispatcher.c
+++ b/libempathy/empathy-dispatcher.c
@@ -112,7 +112,16 @@ typedef struct
   GHashTable *dispatched_channels;
   /* ObjectPath -> EmpathyDispatchOperations */
   GHashTable *dispatching_channels;
-  /* ObjectPath -> EmpathyDispatchOperations */
+
+  /* ObjectPath -> EmpathyDispatchOperations
+   *
+   * This holds channels which were announced with NewChannel while we have an
+   * outstanding channel request for a channel of this type. On the Requests
+   * interface, CreateChannel and EnsureChannel are guaranteed by the spec to
+   * return before NewChannels is emitted, but there was no guarantee of the
+   * ordering of RequestChannel vs. NewChannel. So if necessary, channels are
+   * held in limbo here until we know whether they were requested.
+   */
   GHashTable *outstanding_channels;
   /* List of DispatcherRequestData */
   GList *outstanding_requests;