From 5e6b4bb975fa9697a6aca001629c65db506a437f Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Wed, 18 Jul 2018 18:39:56 +0900
Subject: csapi: Doxy-comments thanks to the latest GTAD

---
 lib/csapi/message_pagination.h | 36 +++++++++++++++++++++++++++++++++---
 1 file changed, 33 insertions(+), 3 deletions(-)

(limited to 'lib/csapi/message_pagination.h')

diff --git a/lib/csapi/message_pagination.h b/lib/csapi/message_pagination.h
index 58900940..890f3ac8 100644
--- a/lib/csapi/message_pagination.h
+++ b/lib/csapi/message_pagination.h
@@ -13,14 +13,39 @@ namespace QMatrixClient
 {
     // Operations
 
+    /// Get a list of events for this room
+    /// 
+    /// This API returns a list of message and state events for a room. It uses
+    /// pagination query parameters to paginate history in the room.
     class GetRoomEventsJob : public BaseJob
     {
         public:
+            /*! Get a list of events for this room
+             * \param roomId 
+             *   The room to get events from.
+             * \param from 
+             *   The token to start returning events from. This token can be obtained
+             *   from a ``prev_batch`` token returned for each room by the sync API,
+             *   or from a ``start`` or ``end`` token returned by a previous request
+             *   to this endpoint.
+             * \param dir 
+             *   The direction to return events from.
+             * \param to 
+             *   The token to stop returning events at. This token can be obtained from
+             *   a ``prev_batch`` token returned for each room by the sync endpoint,
+             *   or from a ``start`` or ``end`` token returned by a previous request to
+             *   this endpoint.
+             * \param limit 
+             *   The maximum number of events to return. Default: 10.
+             * \param filter 
+             *   A JSON RoomEventFilter to filter returned events with.
+             */
             explicit GetRoomEventsJob(const QString& roomId, const QString& from, const QString& dir, const QString& to = {}, Omittable<int> limit = none, const QString& filter = {});
 
-            /** Construct a URL out of baseUrl and usual parameters passed to
-             * GetRoomEventsJob. This function can be used when
-             * a URL for GetRoomEventsJob is necessary but the job
+            /*! Construct a URL without creating a full-fledged job object
+             *
+             * This function can be used when a URL for
+             * GetRoomEventsJob is necessary but the job
              * itself isn't.
              */
             static QUrl makeRequestUrl(QUrl baseUrl, const QString& roomId, const QString& from, const QString& dir, const QString& to = {}, Omittable<int> limit = none, const QString& filter = {});
@@ -29,8 +54,13 @@ namespace QMatrixClient
 
             // Result properties
 
+            /// The token the pagination starts from. If ``dir=b`` this will be
+            /// the token supplied in ``from``.
             const QString& begin() const;
+            /// The token the pagination ends at. If ``dir=b`` this token should
+            /// be used again to request even earlier events.
             const QString& end() const;
+            /// A list of room events.
             RoomEvents&& chunk();
 
         protected:
-- 
cgit v1.2.3