csapi: Doxy-comments thanks to the latest GTAD

1 files changed, 30 insertions, 3 deletions

diff --git a/lib/csapi/peeking_events.h b/lib/csapi/peeking_events.h
index 5f2c4233..f8e8b966 100644
--- a/lib/csapi/peeking_events.h
+++ b/lib/csapi/peeking_events.h
@@ -13,14 +13,36 @@ namespace QMatrixClient
 {
     // Operations
 
+    /// Listen on the event stream.
+    /// 
+    /// This will listen for new events related to a particular room and return
+    /// them to the caller. This will block until an event is received, or until
+    /// the ``timeout`` is reached.
+    /// 
+    /// This API is the same as the normal ``/events`` endpoint, but can be
+    /// called by users who have not joined the room.
+    /// 
+    /// Note that the normal ``/events`` endpoint has been deprecated. This
+    /// API will also be deprecated at some point, but its replacement is not
+    /// yet known.
     class PeekEventsJob : public BaseJob
     {
         public:
+            /*! Listen on the event stream.
+             * \param from 
+             *   The token to stream from. This token is either from a previous
+             *   request to this API or from the initial sync API.
+             * \param timeout 
+             *   The maximum time in milliseconds to wait for an event.
+             * \param roomId 
+             *   The room ID for which events should be returned.
+             */
             explicit PeekEventsJob(const QString& from = {}, Omittable<int> timeout = none, const QString& roomId = {});
 
-            /** Construct a URL out of baseUrl and usual parameters passed to
-             * PeekEventsJob. This function can be used when
-             * a URL for PeekEventsJob is necessary but the job
+            /*! Construct a URL without creating a full-fledged job object
+             *
+             * This function can be used when a URL for
+             * PeekEventsJob is necessary but the job
              * itself isn't.
              */
             static QUrl makeRequestUrl(QUrl baseUrl, const QString& from = {}, Omittable<int> timeout = none, const QString& roomId = {});
@@ -29,8 +51,13 @@ namespace QMatrixClient
 
             // Result properties
 
+            /// A token which correlates to the first value in ``chunk``. This
+            /// is usually the same token supplied to ``from=``.
             const QString& begin() const;
+            /// A token which correlates to the last value in ``chunk``. This
+            /// token should be used in the next request to ``/events``.
             const QString& end() const;
+            /// An array of events.
             RoomEvents&& chunk();
 
         protected: