Improvements in comments

- registerEventType(): comment the cryptic _ variable
- Room::postEvent: document the return value
- Room::Private: upgrade comments to doc-comments - even though in Private, they still are helpful to show hints in IDEs.
- General cleanup

4 files changed, 9 insertions, 6 deletions

diff --git a/lib/converters.h b/lib/converters.h
index 70938ab9..53855a1f 100644
--- a/lib/converters.h
+++ b/lib/converters.h
@@ -61,7 +61,7 @@ namespace QMatrixClient
     inline auto toJson(const QJsonValue& val) { return val; }
     inline auto toJson(const QJsonObject& o) { return o; }
     inline auto toJson(const QJsonArray& arr) { return arr; }
-    // Special-case QStrings and bools to avoid ambiguity between QJsonValue
+    // Special-case QString to avoid ambiguity between QJsonValue
     // and QVariant (also, QString.isEmpty() is used in _impl::AddNode<> below)
     inline auto toJson(const QString& s) { return s; }
 
diff --git a/lib/events/event.h b/lib/events/event.h
index 76e77cf6..c51afcc4 100644
--- a/lib/events/event.h
+++ b/lib/events/event.h
@@ -209,7 +209,7 @@ namespace QMatrixClient
     inline auto registerEventType()
     {
         static const auto _ = setupFactory<EventT>();
-        return _;
+        return _; // Only to facilitate usage in static initialisation
     }
 
     // === Event ===
diff --git a/lib/room.cpp b/lib/room.cpp
index 5dd244f2..088d1d8e 100644
--- a/lib/room.cpp
+++ b/lib/room.cpp
@@ -94,9 +94,11 @@ class Room::Private
         Connection* connection;
         QString id;
         JoinState joinState;
-        // The state of the room at timeline position before-0
+        /// The state of the room at timeline position before-0
+        /// \sa timelineBase
         std::unordered_map<StateEventKey, StateEventPtr> baseState;
-        // The state of the room at timeline position after-maxTimelineIndex()
+        /// The state of the room at timeline position after-maxTimelineIndex()
+        /// \sa Room::syncEdge
         QHash<StateEventKey, const StateEventBase*> currentState;
         Timeline timeline;
         PendingEvents unsyncedEvents;
@@ -156,8 +158,8 @@ class Room::Private
             fileTransfers[tid].status = FileTransferInfo::Failed;
             emit q->fileTransferFailed(tid, errorMessage);
         }
-        // A map from event/txn ids to information about the long operation;
-        // used for both download and upload operations
+        /// A map from event/txn ids to information about the long operation;
+        /// used for both download and upload operations
         QHash<QString, FileTransferPrivateInfo> fileTransfers;
 
         const RoomMessageEvent* getEventWithFile(const QString& eventId) const;
diff --git a/lib/room.h b/lib/room.h
index f1566ac5..a9ed9647 100644
--- a/lib/room.h
+++ b/lib/room.h
@@ -323,6 +323,7 @@ namespace QMatrixClient
              *
              * Takes ownership of the event, deleting it once the matching one
              * arrives with the sync
+             * \return transaction id associated with the event.
              */
             QString postEvent(RoomEvent* event);
             QString postJson(const QString& matrixType,