Document room transitions in .h instead of .cpp

The original comment got a bit rotten, so refresh it as well.

2 files changed, 55 insertions, 13 deletions

diff --git a/connection.cpp b/connection.cpp
index 41160bd2..c940c767 100644
--- a/connection.cpp
+++ b/connection.cpp
@@ -343,22 +343,11 @@ Room* Connection::provideRoom(const QString& id, JoinState joinState)
         return nullptr;
     }
 
-    // Room transitions:
-    // 1. none -> Invite: r=createRoom, emit invitedRoom(r,null)
-    // 2. none -> Join: r=createRoom, emit joinedRoom(r,null)
-    // 3. none -> Leave: r=createRoom, emit leftRoom(r,null)
-    // 4. inv=Invite -> Join: r=createRoom, emit joinedRoom(r,inv), delete Invite
-    // 4a. Leave, inv=Invite -> Join: change state, emit joinedRoom(r,inv), delete Invite
-    // 5. inv=Invite -> Leave: r=createRoom, emit leftRoom(r,inv), delete Invite
-    // 5a. r=Leave, inv=Invite -> Leave: emit leftRoom(r,inv), delete Invite
-    // 6. Join -> Leave: change state
-    // 7. r=Leave -> Invite: inv=createRoom, emit invitedRoom(inv,r)
-    // 8. Leave -> (changes to) Join
     const auto roomKey = qMakePair(id, joinState == JoinState::Invite);
     auto* room = d->roomMap.value(roomKey, nullptr);
     if (room)
     {
-        // Leave is a special case because in transition (5a) above
+        // Leave is a special case because in transition (5a) (see the .h file)
         // joinState == room->joinState but we still have to preempt the Invite
         // and emit a signal. For Invite and Join, there's no such problem.
         if (room->joinState() == joinState && joinState != JoinState::Leave)
diff --git a/connection.h b/connection.h
index 76e4f3c2..adf7a098 100644
--- a/connection.h
+++ b/connection.h
@@ -191,14 +191,67 @@ namespace QMatrixClient
         signals:
             void resolved();
             void connected();
-            void reconnected();
+            void reconnected(); //< Unused; use connected() instead
             void loggedOut();
 
             void syncDone();
+
+            /**
+             * \group Signals emitted on room transitions
+             *
+             * Note: Rooms in Invite state are always stored separately from
+             * rooms in Join/Leave state, because of special treatment of
+             * invite_state in Matrix CS API (see The Spec on /sync for details).
+             * Therefore, objects below are: r - room in Join/Leave state;
+             * i - room in Invite state
+             *
+             * 1. none -> Invite: newRoom(r), invitedRoom(r,nullptr)
+             * 2. none -> Join: newRoom(r), joinedRoom(r,nullptr)
+             * 3. none -> Leave: newRoom(r), leftRoom(r,nullptr)
+             * 4. Invite -> Join:
+             *      newRoom(r), joinedRoom(r,i), aboutToDeleteRoom(i)
+             * 4a. Leave and Invite -> Join:
+             *      joinedRoom(r,i), aboutToDeleteRoom(i)
+             * 5. Invite -> Leave:
+             *      newRoom(r), leftRoom(r,i), aboutToDeleteRoom(i)
+             * 5a. Leave and Invite -> Leave:
+             *      leftRoom(r,i), aboutToDeleteRoom(i)
+             * 6. Join -> Leave: leftRoom(r)
+             * 7. Leave -> Invite: newRoom(i), invitedRoom(i,r)
+             * 8. Leave -> Join: joinedRoom(r)
+             * The following transitions are only possible via forgetRoom()
+             * so far; if a room gets forgotten externally, sync won't tell
+             * about it:
+             * 9. any -> none: as any -> Leave, then aboutToDeleteRoom(r)
+             */
+
+            /** A new room object has been created */
             void newRoom(Room* room);
+
+            /** Invitation to a room received
+             *
+             * If the same room is in Left state, it's passed in prev.
+             */
             void invitedRoom(Room* room, Room* prev);
+
+            /** A room has just been joined
+             *
+             * It's not the same as receiving a room in "join" section of sync
+             * response (rooms will be there even after joining). If this room
+             * was in Invite state before, the respective object is passed in
+             * prev (and it will be deleted shortly afterwards).
+             */
             void joinedRoom(Room* room, Room* prev);
+
+            /** A room has just been left
+             *
+             * If this room has been in Invite state (as in case of rejecting
+             * an invitation), the respective object will be passed in prev
+             * (and will be deleted shortly afterwards).
+             */
             void leftRoom(Room* room, Room* prev);
+
+            /** The room object is about to be deleted */
             void aboutToDeleteRoom(Room* room);
 
             void loginError(QString error);