csapi: Doxy-comments thanks to the latest GTAD

1 files changed, 56 insertions, 0 deletions

diff --git a/lib/csapi/third_party_membership.h b/lib/csapi/third_party_membership.h
index d0c9f811..e8276b3c 100644
--- a/lib/csapi/third_party_membership.h
+++ b/lib/csapi/third_party_membership.h
@@ -11,9 +11,65 @@ namespace QMatrixClient
 {
     // Operations
 
+    /// Invite a user to participate in a particular room.
+    /// 
+    /// .. _invite-by-third-party-id-endpoint:
+    /// 
+    /// *Note that there are two forms of this API, which are documented separately.
+    /// This version of the API does not require that the inviter know the Matrix
+    /// identifier of the invitee, and instead relies on third party identifiers.
+    /// The homeserver uses an identity server to perform the mapping from
+    /// third party identifier to a Matrix identifier. The other is documented in the*
+    /// `joining rooms section`_.
+    /// 
+    /// This API invites a user to participate in a particular room.
+    /// They do not start participating in the room until they actually join the
+    /// room.
+    /// 
+    /// Only users currently in a particular room can invite other users to
+    /// join that room.
+    /// 
+    /// If the identity server did know the Matrix user identifier for the
+    /// third party identifier, the homeserver will append a ``m.room.member``
+    /// event to the room.
+    /// 
+    /// If the identity server does not know a Matrix user identifier for the
+    /// passed third party identifier, the homeserver will issue an invitation
+    /// which can be accepted upon providing proof of ownership of the third
+    /// party identifier. This is achieved by the identity server generating a
+    /// token, which it gives to the inviting homeserver. The homeserver will
+    /// add an ``m.room.third_party_invite`` event into the graph for the room,
+    /// containing that token.
+    /// 
+    /// When the invitee binds the invited third party identifier to a Matrix
+    /// user ID, the identity server will give the user a list of pending
+    /// invitations, each containing:
+    /// 
+    /// - The room ID to which they were invited
+    /// 
+    /// - The token given to the homeserver
+    /// 
+    /// - A signature of the token, signed with the identity server's private key
+    /// 
+    /// - The matrix user ID who invited them to the room
+    /// 
+    /// If a token is requested from the identity server, the homeserver will
+    /// append a ``m.room.third_party_invite`` event to the room.
+    /// 
+    /// .. _joining rooms section: `invite-by-user-id-endpoint`_
     class InviteBy3PIDJob : public BaseJob
     {
         public:
+            /*! Invite a user to participate in a particular room.
+             * \param roomId 
+             *   The room identifier (not alias) to which to invite the user.
+             * \param idServer 
+             *   The hostname+port of the identity server which should be used for third party identifier lookups.
+             * \param medium 
+             *   The kind of address being passed in the address field, for example ``email``.
+             * \param address 
+             *   The invitee's third party identifier.
+             */
             explicit InviteBy3PIDJob(const QString& roomId, const QString& idServer, const QString& medium, const QString& address);
     };
 } // namespace QMatrixClient