diff options
Diffstat (limited to 'lib')
35 files changed, 355 insertions, 341 deletions
diff --git a/lib/application-service/definitions/protocol.h b/lib/application-service/definitions/protocol.h index 6aee9c57..213dbf19 100644 --- a/lib/application-service/definitions/protocol.h +++ b/lib/application-service/definitions/protocol.h @@ -40,7 +40,7 @@ struct ProtocolInstance { /// provided at the higher level Protocol object. QString icon; - /// Preset values for ``fields`` the client may use to search by. + /// Preset values for `fields` the client may use to search by. QJsonObject fields; /// A unique identifier across all instances. @@ -81,10 +81,9 @@ struct ThirdPartyProtocol { /// A content URI representing an icon for the third party protocol. QString icon; - /// The type definitions for the fields defined in the ``user_fields`` and - /// ``location_fields``. Each entry in those arrays MUST have an entry here. - /// The - /// ``string`` key for this object is field name itself. + /// The type definitions for the fields defined in the `user_fields` and + /// `location_fields`. Each entry in those arrays MUST have an entry here. + /// The `string` key for this object is field name itself. /// /// May be an empty object if no fields are defined. QHash<QString, FieldType> fieldTypes; diff --git a/lib/csapi/account-data.h b/lib/csapi/account-data.h index 9a31596f..0c760e80 100644 --- a/lib/csapi/account-data.h +++ b/lib/csapi/account-data.h @@ -12,7 +12,7 @@ namespace Quotient { * * Set some account_data for the client. This config is only visible to the user * that set the account_data. The config will be synced to clients in the - * top-level ``account_data``. + * top-level `account_data`. */ class SetAccountDataJob : public BaseJob { public: @@ -65,7 +65,7 @@ public: * * Set some account_data for the client on a given room. This config is only * visible to the user that set the account_data. The config will be synced to - * clients in the per-room ``account_data``. + * clients in the per-room `account_data`. */ class SetAccountDataPerRoomJob : public BaseJob { public: diff --git a/lib/csapi/administrative_contact.h b/lib/csapi/administrative_contact.h index 1966d533..e436971d 100644 --- a/lib/csapi/administrative_contact.h +++ b/lib/csapi/administrative_contact.h @@ -93,14 +93,14 @@ struct JsonObjectConverter<GetAccount3PIDsJob::ThirdPartyIdentifier> { * * Adds contact information to the user's account. * - * This endpoint is deprecated in favour of the more specific ``/3pid/add`` - * and ``/3pid/bind`` endpoints. + * This endpoint is deprecated in favour of the more specific `/3pid/add` + * and `/3pid/bind` endpoints. * - * .. Note:: - * Previously this endpoint supported a ``bind`` parameter. This parameter - * has been removed, making this endpoint behave as though it was ``false``. - * This results in this endpoint being an equivalent to ``/3pid/bind`` rather - * than dual-purpose. + * **Note:** + * Previously this endpoint supported a `bind` parameter. This parameter + * has been removed, making this endpoint behave as though it was `false`. + * This results in this endpoint being an equivalent to `/3pid/bind` rather + * than dual-purpose. */ class Post3PIDsJob : public BaseJob { public: @@ -144,7 +144,8 @@ struct JsonObjectConverter<Post3PIDsJob::ThreePidCredentials> { /*! \brief Adds contact information to the user's account. * - * This API endpoint uses the `User-Interactive Authentication API`_. + * This API endpoint uses the [User-Interactive Authentication + * API](/client-server-api/#user-interactive-authentication-api). * * Adds contact information to the user's account. Homeservers should use 3PIDs * added through this endpoint for password resets instead of relying on the @@ -206,7 +207,7 @@ public: * Removes a third party identifier from the user's account. This might not * cause an unbind of the identifier from the identity server. * - * Unlike other endpoints, this endpoint does not take an ``id_access_token`` + * Unlike other endpoints, this endpoint does not take an `id_access_token` * parameter because the homeserver is expected to sign the request to the * identity server instead. */ @@ -222,9 +223,9 @@ public: * * \param idServer * The identity server to unbind from. If not provided, the homeserver - * MUST use the ``id_server`` the identifier was added through. If the - * homeserver does not know the original ``id_server``, it MUST return - * a ``id_server_unbind_result`` of ``no-support``. + * MUST use the `id_server` the identifier was added through. If the + * homeserver does not know the original `id_server`, it MUST return + * a `id_server_unbind_result` of `no-support`. */ explicit Delete3pidFromAccountJob(const QString& medium, const QString& address, @@ -233,8 +234,8 @@ public: // Result properties /// An indicator as to whether or not the homeserver was able to unbind - /// the 3PID from the identity server. ``success`` indicates that the - /// indentity server has unbound the identifier whereas ``no-support`` + /// the 3PID from the identity server. `success` indicates that the + /// indentity server has unbound the identifier whereas `no-support` /// indicates that the identity server refuses to support the request /// or the homeserver was not able to determine an identity server to /// unbind from. @@ -249,7 +250,7 @@ public: * Removes a user's third party identifier from the provided identity server * without removing it from the homeserver. * - * Unlike other endpoints, this endpoint does not take an ``id_access_token`` + * Unlike other endpoints, this endpoint does not take an `id_access_token` * parameter because the homeserver is expected to sign the request to the * identity server instead. */ @@ -265,9 +266,9 @@ public: * * \param idServer * The identity server to unbind from. If not provided, the homeserver - * MUST use the ``id_server`` the identifier was added through. If the - * homeserver does not know the original ``id_server``, it MUST return - * a ``id_server_unbind_result`` of ``no-support``. + * MUST use the `id_server` the identifier was added through. If the + * homeserver does not know the original `id_server`, it MUST return + * a `id_server_unbind_result` of `no-support`. */ explicit Unbind3pidFromAccountJob(const QString& medium, const QString& address, @@ -276,8 +277,8 @@ public: // Result properties /// An indicator as to whether or not the identity server was able to unbind - /// the 3PID. ``success`` indicates that the identity server has unbound the - /// identifier whereas ``no-support`` indicates that the identity server + /// the 3PID. `success` indicates that the identity server has unbound the + /// identifier whereas `no-support` indicates that the identity server /// refuses to support the request or the homeserver was not able to /// determine an identity server to unbind from. QString idServerUnbindResult() const @@ -293,7 +294,9 @@ public: * already associated with an account on this homeserver. This API should * be used to request validation tokens when adding an email address to an * account. This API's parameters and response are identical to that of - * the |/register/email/requestToken|_ endpoint. The homeserver should validate + * the + * [`/register/email/requestToken`](/client-server-api/#post_matrixclientr0registeremailrequesttoken) + * endpoint. The homeserver should validate * the email itself, either by sending a validation email itself or by using * a service it has control over. */ @@ -307,9 +310,11 @@ public: * already associated with an account on this homeserver. This API should * be used to request validation tokens when adding an email address to an * account. This API's parameters and response are identical to that of - * the |/register/email/requestToken|_ endpoint. The homeserver should - * validate the email itself, either by sending a validation email itself or - * by using a service it has control over. + * the + * [`/register/email/requestToken`](/client-server-api/#post_matrixclientr0registeremailrequesttoken) + * endpoint. The homeserver should validate + * the email itself, either by sending a validation email itself or by + * using a service it has control over. */ explicit RequestTokenTo3PIDEmailJob(const EmailValidationData& body); @@ -331,7 +336,9 @@ public: * already associated with an account on this homeserver. This API should * be used to request validation tokens when adding a phone number to an * account. This API's parameters and response are identical to that of - * the |/register/msisdn/requestToken|_ endpoint. The homeserver should validate + * the + * [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientr0registermsisdnrequesttoken) + * endpoint. The homeserver should validate * the phone number itself, either by sending a validation message itself or by * using a service it has control over. */ @@ -345,9 +352,11 @@ public: * already associated with an account on this homeserver. This API should * be used to request validation tokens when adding a phone number to an * account. This API's parameters and response are identical to that of - * the |/register/msisdn/requestToken|_ endpoint. The homeserver should - * validate the phone number itself, either by sending a validation message - * itself or by using a service it has control over. + * the + * [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientr0registermsisdnrequesttoken) + * endpoint. The homeserver should validate + * the phone number itself, either by sending a validation message itself + * or by using a service it has control over. */ explicit RequestTokenTo3PIDMSISDNJob(const MsisdnValidationData& body); diff --git a/lib/csapi/appservice_room_directory.h b/lib/csapi/appservice_room_directory.h index 3fa02a07..2631f38c 100644 --- a/lib/csapi/appservice_room_directory.h +++ b/lib/csapi/appservice_room_directory.h @@ -17,9 +17,9 @@ namespace Quotient { * This API is similar to the room directory visibility API used by clients * to update the homeserver's more general room directory. * - * This API requires the use of an application service access token - * (``as_token``) instead of a typical client's access_token. This API cannot be - * invoked by users who are not identified as application services. + * This API requires the use of an application service access token (`as_token`) + * instead of a typical client's access_token. This API cannot be invoked by + * users who are not identified as application services. */ class UpdateAppserviceRoomDirectoryVsibilityJob : public BaseJob { public: diff --git a/lib/csapi/banning.h b/lib/csapi/banning.h index 37ae91ee..48c054c2 100644 --- a/lib/csapi/banning.h +++ b/lib/csapi/banning.h @@ -30,7 +30,8 @@ public: * * \param reason * The reason the user has been banned. This will be supplied as the - * ``reason`` on the target's updated `m.room.member`_ event. + * `reason` on the target's updated + * [`m.room.member`](/client-server-api/#mroommember) event. */ explicit BanJob(const QString& roomId, const QString& userId, const QString& reason = {}); diff --git a/lib/csapi/content-repo.h b/lib/csapi/content-repo.h index ed67485c..f3d7309a 100644 --- a/lib/csapi/content-repo.h +++ b/lib/csapi/content-repo.h @@ -32,7 +32,8 @@ public: // Result properties - /// The `MXC URI`_ to the uploaded content. + /// The [MXC URI](/client-server-api/#matrix-content-mxc-uris) to the + /// uploaded content. QString contentUri() const { return loadFromJson<QString>("content_uri"_ls); @@ -47,10 +48,10 @@ public: /*! \brief Download content from the content repository. * * \param serverName - * The server name from the ``mxc://`` URI (the authoritory component) + * The server name from the `mxc://` URI (the authoritory component) * * \param mediaId - * The media ID from the ``mxc://`` URI (the path component) + * The media ID from the `mxc://` URI (the path component) * * \param allowRemote * Indicates to the server that it should not attempt to fetch the media @@ -95,13 +96,13 @@ public: * name * * \param serverName - * The server name from the ``mxc://`` URI (the authoritory component) + * The server name from the `mxc://` URI (the authoritory component) * * \param mediaId - * The media ID from the ``mxc://`` URI (the path component) + * The media ID from the `mxc://` URI (the path component) * * \param fileName - * A filename to give in the ``Content-Disposition`` header. + * A filename to give in the `Content-Disposition` header. * * \param allowRemote * Indicates to the server that it should not attempt to fetch the media @@ -127,7 +128,7 @@ public: /// The content type of the file that was previously uploaded. QString contentType() const { return reply()->rawHeader("Content-Type"); } - /// The ``fileName`` requested or the name of the file that was previously + /// The `fileName` requested or the name of the file that was previously /// uploaded, if set. QString contentDisposition() const { @@ -141,17 +142,18 @@ public: /*! \brief Download a thumbnail of content from the content repository * * Download a thumbnail of content from the content repository. - * See the `thumbnailing <#thumbnails>`_ section for more information. + * See the [Thumbnails](/client-server-api/#thumbnails) section for more + * information. */ class GetContentThumbnailJob : public BaseJob { public: /*! \brief Download a thumbnail of content from the content repository * * \param serverName - * The server name from the ``mxc://`` URI (the authoritory component) + * The server name from the `mxc://` URI (the authoritory component) * * \param mediaId - * The media ID from the ``mxc://`` URI (the path component) + * The media ID from the `mxc://` URI (the path component) * * \param width * The *desired* width of the thumbnail. The actual thumbnail may be @@ -162,8 +164,8 @@ public: * larger than the size specified. * * \param method - * The desired resizing method. See the `thumbnailing <#thumbnails>`_ - * section for more information. + * The desired resizing method. See the + * [Thumbnails](/client-server-api/#thumbnails) section for more information. * * \param allowRemote * Indicates to the server that it should not attempt to fetch @@ -199,11 +201,11 @@ public: * Get information about a URL for the client. Typically this is called when a * client sees a URL in a message and wants to render a preview for the user. * - * .. Note:: - * Clients should consider avoiding this endpoint for URLs posted in encrypted - * rooms. Encrypted rooms often contain more sensitive information the users - * do not want to share with the homeserver, and this can mean that the URLs - * being shared should also not be shared with the homeserver. + * **Note:** + * Clients should consider avoiding this endpoint for URLs posted in encrypted + * rooms. Encrypted rooms often contain more sensitive information the users + * do not want to share with the homeserver, and this can mean that the URLs + * being shared should also not be shared with the homeserver. */ class GetUrlPreviewJob : public BaseJob { public: @@ -235,7 +237,8 @@ public: return loadFromJson<Omittable<qint64>>("matrix:image:size"_ls); } - /// An `MXC URI`_ to the image. Omitted if there is no image. + /// An [MXC URI](/client-server-api/#matrix-content-mxc-uris) to the image. + /// Omitted if there is no image. QString ogImage() const { return loadFromJson<QString>("og:image"_ls); } }; diff --git a/lib/csapi/create_room.h b/lib/csapi/create_room.h index 6a718ff4..81dfbffc 100644 --- a/lib/csapi/create_room.h +++ b/lib/csapi/create_room.h @@ -16,47 +16,42 @@ namespace Quotient { * the new room, including checking power levels for each event. It MUST * apply the events implied by the request in the following order: * - * 1. The ``m.room.create`` event itself. Must be the first event in the + * 1. The `m.room.create` event itself. Must be the first event in the * room. * - * 2. An ``m.room.member`` event for the creator to join the room. This is + * 2. An `m.room.member` event for the creator to join the room. This is * needed so the remaining events can be sent. * - * 3. A default ``m.room.power_levels`` event, giving the room creator + * 3. A default `m.room.power_levels` event, giving the room creator * (and not other members) permission to send state events. Overridden - * by the ``power_level_content_override`` parameter. + * by the `power_level_content_override` parameter. * - * 4. Events set by the ``preset``. Currently these are the - * ``m.room.join_rules``, - * ``m.room.history_visibility``, and ``m.room.guest_access`` state events. + * 4. Events set by the `preset`. Currently these are the `m.room.join_rules`, + * `m.room.history_visibility`, and `m.room.guest_access` state events. * - * 5. Events listed in ``initial_state``, in the order that they are + * 5. Events listed in `initial_state`, in the order that they are * listed. * - * 6. Events implied by ``name`` and ``topic`` (``m.room.name`` and - * ``m.room.topic`` state events). + * 6. Events implied by `name` and `topic` (`m.room.name` and `m.room.topic` + * state events). * - * 7. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` - * with - * ``membership: invite`` and ``m.room.third_party_invite``). + * 7. Invite events implied by `invite` and `invite_3pid` (`m.room.member` with + * `membership: invite` and `m.room.third_party_invite`). * * The available presets do the following with respect to room state: * - * ======================== ============== ====================== - * ================ ========= Preset ``join_rules`` - * ``history_visibility`` ``guest_access`` Other - * ======================== ============== ====================== - * ================ ========= - * ``private_chat`` ``invite`` ``shared`` ``can_join`` - * ``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All - * invitees are given the same power level as the room creator. - * ``public_chat`` ``public`` ``shared`` ``forbidden`` - * ======================== ============== ====================== - * ================ ========= + * | Preset | `join_rules` | `history_visibility` | + * `guest_access` | Other | + * |------------------------|--------------|----------------------|----------------|-------| + * | `private_chat` | `invite` | `shared` | `can_join` + * | | | `trusted_private_chat` | `invite` | `shared` | + * `can_join` | All invitees are given the same power level as the room + * creator. | | `public_chat` | `public` | `shared` | + * `forbidden` | | * - * The server will create a ``m.room.create`` event in the room with the + * The server will create a `m.room.create` event in the room with the * requesting user as the creator, alongside other keys provided in the - * ``creation_content``. + * `creation_content`. */ class CreateRoomJob : public BaseJob { public: @@ -68,50 +63,44 @@ public: /// the new room, including checking power levels for each event. It MUST /// apply the events implied by the request in the following order: /// - /// 1. The ``m.room.create`` event itself. Must be the first event in the + /// 1. The `m.room.create` event itself. Must be the first event in the /// room. /// - /// 2. An ``m.room.member`` event for the creator to join the room. This is + /// 2. An `m.room.member` event for the creator to join the room. This is /// needed so the remaining events can be sent. /// - /// 3. A default ``m.room.power_levels`` event, giving the room creator + /// 3. A default `m.room.power_levels` event, giving the room creator /// (and not other members) permission to send state events. Overridden - /// by the ``power_level_content_override`` parameter. + /// by the `power_level_content_override` parameter. /// - /// 4. Events set by the ``preset``. Currently these are the - /// ``m.room.join_rules``, - /// ``m.room.history_visibility``, and ``m.room.guest_access`` state - /// events. + /// 4. Events set by the `preset`. Currently these are the + /// `m.room.join_rules`, + /// `m.room.history_visibility`, and `m.room.guest_access` state events. /// - /// 5. Events listed in ``initial_state``, in the order that they are + /// 5. Events listed in `initial_state`, in the order that they are /// listed. /// - /// 6. Events implied by ``name`` and ``topic`` (``m.room.name`` and - /// ``m.room.topic`` + /// 6. Events implied by `name` and `topic` (`m.room.name` and `m.room.topic` /// state events). /// - /// 7. Invite events implied by ``invite`` and ``invite_3pid`` - /// (``m.room.member`` with - /// ``membership: invite`` and ``m.room.third_party_invite``). + /// 7. Invite events implied by `invite` and `invite_3pid` (`m.room.member` + /// with + /// `membership: invite` and `m.room.third_party_invite`). /// /// The available presets do the following with respect to room state: /// - /// ======================== ============== ====================== - /// ================ ========= - /// Preset ``join_rules`` ``history_visibility`` - /// ``guest_access`` Other - /// ======================== ============== ====================== - /// ================ ========= - /// ``private_chat`` ``invite`` ``shared`` ``can_join`` - /// ``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All - /// invitees are given the same power level as the room creator. - /// ``public_chat`` ``public`` ``shared`` ``forbidden`` - /// ======================== ============== ====================== - /// ================ ========= + /// | Preset | `join_rules` | `history_visibility` | + /// `guest_access` | Other | + /// |------------------------|--------------|----------------------|----------------|-------| + /// | `private_chat` | `invite` | `shared` | + /// `can_join` | | | `trusted_private_chat` | `invite` | + /// `shared` | `can_join` | All invitees are given the same + /// power level as the room creator. | | `public_chat` | `public` + /// | `shared` | `forbidden` | | /// - /// The server will create a ``m.room.create`` event in the room with the + /// The server will create a `m.room.create` event in the room with the /// requesting user as the creator, alongside other keys provided in the - /// ``creation_content``. + /// `creation_content`. struct Invite3pid { /// The hostname+port of the identity server which should be used for /// third party identifier lookups. @@ -121,7 +110,7 @@ public: /// r0.5-compatible clients and this specification version. QString idAccessToken; /// The kind of address being passed in the address field, for example - /// ``email``. + /// `email`. QString medium; /// The invitee's third party identifier. QString address; @@ -133,50 +122,44 @@ public: /// the new room, including checking power levels for each event. It MUST /// apply the events implied by the request in the following order: /// - /// 1. The ``m.room.create`` event itself. Must be the first event in the + /// 1. The `m.room.create` event itself. Must be the first event in the /// room. /// - /// 2. An ``m.room.member`` event for the creator to join the room. This is + /// 2. An `m.room.member` event for the creator to join the room. This is /// needed so the remaining events can be sent. /// - /// 3. A default ``m.room.power_levels`` event, giving the room creator + /// 3. A default `m.room.power_levels` event, giving the room creator /// (and not other members) permission to send state events. Overridden - /// by the ``power_level_content_override`` parameter. + /// by the `power_level_content_override` parameter. /// - /// 4. Events set by the ``preset``. Currently these are the - /// ``m.room.join_rules``, - /// ``m.room.history_visibility``, and ``m.room.guest_access`` state - /// events. + /// 4. Events set by the `preset`. Currently these are the + /// `m.room.join_rules`, + /// `m.room.history_visibility`, and `m.room.guest_access` state events. /// - /// 5. Events listed in ``initial_state``, in the order that they are + /// 5. Events listed in `initial_state`, in the order that they are /// listed. /// - /// 6. Events implied by ``name`` and ``topic`` (``m.room.name`` and - /// ``m.room.topic`` + /// 6. Events implied by `name` and `topic` (`m.room.name` and `m.room.topic` /// state events). /// - /// 7. Invite events implied by ``invite`` and ``invite_3pid`` - /// (``m.room.member`` with - /// ``membership: invite`` and ``m.room.third_party_invite``). + /// 7. Invite events implied by `invite` and `invite_3pid` (`m.room.member` + /// with + /// `membership: invite` and `m.room.third_party_invite`). /// /// The available presets do the following with respect to room state: /// - /// ======================== ============== ====================== - /// ================ ========= - /// Preset ``join_rules`` ``history_visibility`` - /// ``guest_access`` Other - /// ======================== ============== ====================== - /// ================ ========= - /// ``private_chat`` ``invite`` ``shared`` ``can_join`` - /// ``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All - /// invitees are given the same power level as the room creator. - /// ``public_chat`` ``public`` ``shared`` ``forbidden`` - /// ======================== ============== ====================== - /// ================ ========= + /// | Preset | `join_rules` | `history_visibility` | + /// `guest_access` | Other | + /// |------------------------|--------------|----------------------|----------------|-------| + /// | `private_chat` | `invite` | `shared` | + /// `can_join` | | | `trusted_private_chat` | `invite` | + /// `shared` | `can_join` | All invitees are given the same + /// power level as the room creator. | | `public_chat` | `public` + /// | `shared` | `forbidden` | | /// - /// The server will create a ``m.room.create`` event in the room with the + /// The server will create a `m.room.create` event in the room with the /// requesting user as the creator, alongside other keys provided in the - /// ``creation_content``. + /// `creation_content`. struct StateEvent { /// The type of event to send. QString type; @@ -191,12 +174,12 @@ public: /*! \brief Create a new room * * \param visibility - * A ``public`` visibility indicates that the room will be shown - * in the published room list. A ``private`` visibility will hide + * A `public` visibility indicates that the room will be shown + * in the published room list. A `private` visibility will hide * the room from the published room list. Rooms default to - * ``private`` visibility if this key is not included. NB: This - * should not be confused with ``join_rules`` which also uses the - * word ``public``. + * `private` visibility if this key is not included. NB: This + * should not be confused with `join_rules` which also uses the + * word `public`. * * \param roomAliasName * The desired room alias **local part**. If this is included, a @@ -204,20 +187,20 @@ public: * room. The alias will belong on the *same* homeserver which * created the room. For example, if this was set to "foo" and * sent to the homeserver "example.com" the complete room alias - * would be ``#foo:example.com``. + * would be `#foo:example.com`. * * The complete room alias will become the canonical alias for * the room. * * \param name - * If this is included, an ``m.room.name`` event will be sent + * If this is included, an `m.room.name` event will be sent * into the room to indicate the name of the room. See Room - * Events for more information on ``m.room.name``. + * Events for more information on `m.room.name`. * * \param topic - * If this is included, an ``m.room.topic`` event will be sent + * If this is included, an `m.room.topic` event will be sent * into the room to indicate the topic for the room. See Room - * Events for more information on ``m.room.topic``. + * Events for more information on `m.room.topic`. * * \param invite * A list of user IDs to invite to the room. This will tell the @@ -230,14 +213,14 @@ public: * \param roomVersion * The room version to set for the room. If not provided, the homeserver * is to use its configured default. If provided, the homeserver will return - * a 400 error with the errcode ``M_UNSUPPORTED_ROOM_VERSION`` if it does - * not support the room version. + * a 400 error with the errcode `M_UNSUPPORTED_ROOM_VERSION` if it does not + * support the room version. * * \param creationContent - * Extra keys, such as ``m.federate``, to be added to the content - * of the `m.room.create`_ event. The server will clobber the following - * keys: ``creator``, ``room_version``. Future versions of the - * specification may allow the server to clobber other keys. + * Extra keys, such as `m.federate`, to be added to the content + * of the [`m.room.create`](client-server-api/#mroomcreate) event. The + * server will clobber the following keys: `creator`, `room_version`. Future + * versions of the specification may allow the server to clobber other keys. * * \param initialState * A list of state events to set in the new room. This allows @@ -245,28 +228,30 @@ public: * room. The expected format of the state events are an object * with type, state_key and content keys set. * - * Takes precedence over events set by ``preset``, but gets - * overriden by ``name`` and ``topic`` keys. + * Takes precedence over events set by `preset`, but gets + * overriden by `name` and `topic` keys. * * \param preset * Convenience parameter for setting various default state events * based on a preset. * - * If unspecified, the server should use the ``visibility`` to determine - * which preset to use. A visbility of ``public`` equates to a preset of - * ``public_chat`` and ``private`` visibility equates to a preset of - * ``private_chat``. + * If unspecified, the server should use the `visibility` to determine + * which preset to use. A visbility of `public` equates to a preset of + * `public_chat` and `private` visibility equates to a preset of + * `private_chat`. * * \param isDirect - * This flag makes the server set the ``is_direct`` flag on the - * ``m.room.member`` events sent to the users in ``invite`` and - * ``invite_3pid``. See `Direct Messaging`_ for more information. + * This flag makes the server set the `is_direct` flag on the + * `m.room.member` events sent to the users in `invite` and + * `invite_3pid`. See [Direct + * Messaging](/client-server-api/#direct-messaging) for more information. * * \param powerLevelContentOverride * The power level content to override in the default power level * event. This object is applied on top of the generated - * `m.room.power_levels`_ event content prior to it being sent to the room. - * Defaults to overriding nothing. + * [`m.room.power_levels`](client-server-api/#mroompower_levels) + * event content prior to it being sent to the room. Defaults to + * overriding nothing. */ explicit CreateRoomJob(const QString& visibility = {}, const QString& roomAliasName = {}, diff --git a/lib/csapi/definitions/device_keys.h b/lib/csapi/definitions/device_keys.h index 3065f218..84ecefae 100644 --- a/lib/csapi/definitions/device_keys.h +++ b/lib/csapi/definitions/device_keys.h @@ -21,15 +21,15 @@ struct DeviceKeys { QStringList algorithms; /// Public identity keys. The names of the properties should be in the - /// format ``<algorithm>:<device_id>``. The keys themselves should be + /// format `<algorithm>:<device_id>`. The keys themselves should be /// encoded as specified by the key algorithm. QHash<QString, QString> keys; /// Signatures for the device key object. A map from user ID, to a map from - /// ``<algorithm>:<device_id>`` to the signature. + /// `<algorithm>:<device_id>` to the signature. /// - /// The signature is calculated using the process described at `Signing - /// JSON`_. + /// The signature is calculated using the process described at [Signing + /// JSON](/appendices/#signing-json). QHash<QString, QHash<QString, QString>> signatures; }; diff --git a/lib/csapi/definitions/event_filter.h b/lib/csapi/definitions/event_filter.h index 67497412..c55d4f92 100644 --- a/lib/csapi/definitions/event_filter.h +++ b/lib/csapi/definitions/event_filter.h @@ -14,13 +14,13 @@ struct EventFilter { /// A list of sender IDs to exclude. If this list is absent then no senders /// are excluded. A matching sender will be excluded even if it is listed in - /// the ``'senders'`` filter. + /// the `'senders'` filter. QStringList notSenders; /// A list of event types to exclude. If this list is absent then no event /// types are excluded. A matching type will be excluded even if it is - /// listed in the ``'types'`` filter. A '*' can be used as a wildcard to - /// match any sequence of characters. + /// listed in the `'types'` filter. A '*' can be used as a wildcard to match + /// any sequence of characters. QStringList notTypes; /// A list of senders IDs to include. If this list is absent then all @@ -28,7 +28,7 @@ struct EventFilter { QStringList senders; /// A list of event types to include. If this list is absent then all event - /// types are included. A ``'*'`` can be used as a wildcard to match any + /// types are included. A `'*'` can be used as a wildcard to match any /// sequence of characters. QStringList types; }; diff --git a/lib/csapi/definitions/openid_token.h b/lib/csapi/definitions/openid_token.h index 5e68c376..3c447321 100644 --- a/lib/csapi/definitions/openid_token.h +++ b/lib/csapi/definitions/openid_token.h @@ -11,10 +11,10 @@ namespace Quotient { struct OpenidToken { /// An access token the consumer may use to verify the identity of /// the person who generated the token. This is given to the federation - /// API ``GET /openid/userinfo`` to verify the user's identity. + /// API `GET /openid/userinfo` to verify the user's identity. QString accessToken; - /// The string ``Bearer``. + /// The string `Bearer`. QString tokenType; /// The homeserver domain the consumer should use when attempting to diff --git a/lib/csapi/definitions/push_condition.h b/lib/csapi/definitions/push_condition.h index a6decf1b..ce66d075 100644 --- a/lib/csapi/definitions/push_condition.h +++ b/lib/csapi/definitions/push_condition.h @@ -9,26 +9,27 @@ namespace Quotient { struct PushCondition { - /// The kind of condition to apply. See `conditions <#conditions>`_ for - /// more information on the allowed kinds and how they work. + /// The kind of condition to apply. See + /// [conditions](/client-server-api/#conditions) for more information on the + /// allowed kinds and how they work. QString kind; - /// Required for ``event_match`` conditions. The dot-separated field of the + /// Required for `event_match` conditions. The dot-separated field of the /// event to match. /// - /// Required for ``sender_notification_permission`` conditions. The field in + /// Required for `sender_notification_permission` conditions. The field in /// the power level event the user needs a minimum power level for. Fields - /// must be specified under the ``notifications`` property in the power - /// level event's ``content``. + /// must be specified under the `notifications` property in the power level + /// event's `content`. QString key; - /// Required for ``event_match`` conditions. The glob-style pattern to + /// Required for `event_match` conditions. The glob-style pattern to /// match against. Patterns with no special glob characters should be /// treated as having asterisks prepended and appended when testing the /// condition. QString pattern; - /// Required for ``room_member_count`` conditions. A decimal integer + /// Required for `room_member_count` conditions. A decimal integer /// optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches /// rooms where the member count is strictly less than the given number and /// so forth. If no prefix is present, this parameter defaults to ==. diff --git a/lib/csapi/definitions/push_rule.h b/lib/csapi/definitions/push_rule.h index 43749bae..135537c1 100644 --- a/lib/csapi/definitions/push_rule.h +++ b/lib/csapi/definitions/push_rule.h @@ -25,10 +25,10 @@ struct PushRule { /// The conditions that must hold true for an event in order for a rule to /// be applied to an event. A rule with no conditions always matches. Only - /// applicable to ``underride`` and ``override`` rules. + /// applicable to `underride` and `override` rules. QVector<PushCondition> conditions; - /// The glob-style pattern to match against. Only applicable to ``content`` + /// The glob-style pattern to match against. Only applicable to `content` /// rules. QString pattern; }; diff --git a/lib/csapi/device_management.h b/lib/csapi/device_management.h index 47dc7ec8..7fb69873 100644 --- a/lib/csapi/device_management.h +++ b/lib/csapi/device_management.h @@ -83,7 +83,8 @@ public: /*! \brief Delete a device * - * This API endpoint uses the `User-Interactive Authentication API`_. + * This API endpoint uses the [User-Interactive Authentication + * API](/client-server-api/#user-interactive-authentication-api). * * Deletes the given device, and invalidates any access token associated with it. */ @@ -104,7 +105,8 @@ public: /*! \brief Bulk deletion of devices * - * This API endpoint uses the `User-Interactive Authentication API`_. + * This API endpoint uses the [User-Interactive Authentication + * API](/client-server-api/#user-interactive-authentication-api). * * Deletes the given devices, and invalidates any access token associated with * them. diff --git a/lib/csapi/directory.h b/lib/csapi/directory.h index 9b109aad..93a31595 100644 --- a/lib/csapi/directory.h +++ b/lib/csapi/directory.h @@ -68,13 +68,13 @@ public: * instance that room aliases can only be deleted by their creator or a server * administrator. * - * .. Note:: - * Servers may choose to update the ``alt_aliases`` for the - * ``m.room.canonical_alias`` state event in the room when an alias is removed. + * **Note:** + * Servers may choose to update the `alt_aliases` for the + * `m.room.canonical_alias` state event in the room when an alias is removed. * Servers which choose to update the canonical alias event are recommended to, * in addition to their other relevant permission checks, delete the alias and * return a successful response even if the user does not have permission to - * update the ``m.room.canonical_alias`` event. + * update the `m.room.canonical_alias` event. */ class DeleteRoomAliasJob : public BaseJob { public: @@ -99,18 +99,18 @@ public: * given room. * * This endpoint can be called by users who are in the room (external - * users receive an ``M_FORBIDDEN`` error response). If the room's - * ``m.room.history_visibility`` maps to ``world_readable``, any + * users receive an `M_FORBIDDEN` error response). If the room's + * `m.room.history_visibility` maps to `world_readable`, any * user can call this endpoint. * * Servers may choose to implement additional access control checks here, * such as allowing server administrators to view aliases regardless of * membership. * - * .. Note:: - * Clients are recommended not to display this list of aliases prominently - * as they are not curated, unlike those listed in the - * ``m.room.canonical_alias`` state event. + * **Note:** + * Clients are recommended not to display this list of aliases prominently + * as they are not curated, unlike those listed in the `m.room.canonical_alias` + * state event. */ class GetLocalAliasesJob : public BaseJob { public: diff --git a/lib/csapi/event_context.h b/lib/csapi/event_context.h index d82d16ab..4e50edf3 100644 --- a/lib/csapi/event_context.h +++ b/lib/csapi/event_context.h @@ -16,8 +16,8 @@ namespace Quotient { * surrounding an event. * * *Note*: This endpoint supports lazy-loading of room member events. See - * `Lazy-loading room members <#lazy-loading-room-members>`_ for more - * information. + * [Lazy-loading room members](/client-server-api/#lazy-loading-room-members) + * for more information. */ class GetEventContextJob : public BaseJob { public: @@ -33,13 +33,13 @@ public: * The maximum number of events to return. Default: 10. * * \param filter - * A JSON ``RoomEventFilter`` to filter the returned events with. The - * filter is only applied to ``events_before``, ``events_after``, and - * ``state``. It is not applied to the ``event`` itself. The filter may - * be applied before or/and after the ``limit`` parameter - whichever the + * A JSON `RoomEventFilter` to filter the returned events with. The + * filter is only applied to `events_before`, `events_after`, and + * `state`. It is not applied to the `event` itself. The filter may + * be applied before or/and after the `limit` parameter - whichever the * homeserver prefers. * - * See `Filtering <#filtering>`_ for more information. + * See [Filtering](/client-server-api/#filtering) for more information. */ explicit GetEventContextJob(const QString& roomId, const QString& eventId, Omittable<int> limit = none, diff --git a/lib/csapi/filter.h b/lib/csapi/filter.h index f07b489c..01bec36b 100644 --- a/lib/csapi/filter.h +++ b/lib/csapi/filter.h @@ -32,7 +32,7 @@ public: // Result properties /// The ID of the filter that was created. Cannot start - /// with a ``{`` as this character is used to determine + /// with a `{` as this character is used to determine /// if the filter provided is inline JSON or a previously /// declared filter by homeservers on some APIs. QString filterId() const { return loadFromJson<QString>("filter_id"_ls); } diff --git a/lib/csapi/inviting.h b/lib/csapi/inviting.h index 59a61b89..1e65ecff 100644 --- a/lib/csapi/inviting.h +++ b/lib/csapi/inviting.h @@ -10,12 +10,11 @@ namespace Quotient { /*! \brief Invite a user to participate in a particular room. * - * .. _invite-by-user-id-endpoint: - * * *Note that there are two forms of this API, which are documented separately. * This version of the API requires that the inviter knows the Matrix * identifier of the invitee. The other is documented in the* - * `third party invites section`_. + * [third party invites + * section](/client-server-api/#post_matrixclientr0roomsroomidinvite-1). * * This API invites a user to participate in a particular room. * They do not start participating in the room until they actually join the @@ -25,9 +24,7 @@ namespace Quotient { * join that room. * * If the user was invited to the room, the homeserver will append a - * ``m.room.member`` event to the room. - * - * .. _third party invites section: `invite-by-third-party-id-endpoint`_ + * `m.room.member` event to the room. */ class InviteUserJob : public BaseJob { public: diff --git a/lib/csapi/joining.h b/lib/csapi/joining.h index dd936f92..1b6f99e4 100644 --- a/lib/csapi/joining.h +++ b/lib/csapi/joining.h @@ -13,7 +13,7 @@ namespace Quotient { /*! \brief Start the requesting user participating in a particular room. * * *Note that this API requires a room ID, not alias.* - * ``/join/{roomIdOrAlias}`` *exists if you have a room alias.* + * `/join/{roomIdOrAlias}` *exists if you have a room alias.* * * This API starts a user participating in a particular room, if that user * is allowed to participate in that room. After this call, the client is @@ -21,7 +21,9 @@ namespace Quotient { * events associated with the room until the user leaves the room. * * After a user has joined a room, the room will appear as an entry in the - * response of the |/initialSync|_ and |/sync|_ APIs. + * response of the + * [`/initialSync`](/client-server-api/#get_matrixclientr0initialsync) and + * [`/sync`](/client-server-api/#get_matrixclientr0sync) APIs. */ class JoinRoomByIdJob : public BaseJob { public: @@ -32,7 +34,7 @@ public: * * \param thirdPartySigned * If supplied, the homeserver must verify that it matches a pending - * ``m.room.third_party_invite`` event in the room, and perform + * `m.room.third_party_invite` event in the room, and perform * key validity checking if required by the event. */ explicit JoinRoomByIdJob( @@ -48,7 +50,7 @@ public: /*! \brief Start the requesting user participating in a particular room. * * *Note that this API takes either a room ID or alias, unlike* - * ``/room/{roomId}/join``. + * `/room/{roomId}/join`. * * This API starts a user participating in a particular room, if that user * is allowed to participate in that room. After this call, the client is @@ -56,7 +58,9 @@ public: * events associated with the room until the user leaves the room. * * After a user has joined a room, the room will appear as an entry in the - * response of the |/initialSync|_ and |/sync|_ APIs. + * response of the + * [`/initialSync`](/client-server-api/#get_matrixclientr0initialsync) and + * [`/sync`](/client-server-api/#get_matrixclientr0sync) APIs. */ class JoinRoomJob : public BaseJob { public: @@ -70,8 +74,8 @@ public: * must be participating in the room. * * \param thirdPartySigned - * If a ``third_party_signed`` was supplied, the homeserver must verify - * that it matches a pending ``m.room.third_party_invite`` event in the + * If a `third_party_signed` was supplied, the homeserver must verify + * that it matches a pending `m.room.third_party_invite` event in the * room, and perform key validity checking if required by the event. */ explicit JoinRoomJob( diff --git a/lib/csapi/keys.h b/lib/csapi/keys.h index 8f6c8cc9..621945eb 100644 --- a/lib/csapi/keys.h +++ b/lib/csapi/keys.h @@ -25,8 +25,8 @@ public: * \param oneTimeKeys * One-time public keys for "pre-key" messages. The names of * the properties should be in the format - * ``<algorithm>:<key_id>``. The format of the key is determined - * by the `key algorithm <#key-algorithms>`_. + * `<algorithm>:<key_id>`. The format of the key is determined + * by the [key algorithm](/client-server-api/#key-algorithms). * * May be absent if no new one-time keys are required. */ @@ -98,7 +98,7 @@ public: /// /// If the homeserver could be reached, but the user or device /// was unknown, no failure is recorded. Instead, the corresponding - /// user or device is missing from the ``device_keys`` result. + /// user or device is missing from the `device_keys` result. QHash<QString, QJsonObject> failures() const { return loadFromJson<QHash<QString, QJsonObject>>("failures"_ls); @@ -107,7 +107,7 @@ public: /// Information on the queried devices. A map from user ID, to a /// map from device ID to device information. For each device, /// the information returned will be the same as uploaded via - /// ``/keys/upload``, with the addition of an ``unsigned`` + /// `/keys/upload`, with the addition of an `unsigned` /// property. QHash<QString, QHash<QString, DeviceInformation>> deviceKeys() const { @@ -163,18 +163,17 @@ public: /// /// If the homeserver could be reached, but the user or device /// was unknown, no failure is recorded. Instead, the corresponding - /// user or device is missing from the ``one_time_keys`` result. + /// user or device is missing from the `one_time_keys` result. QHash<QString, QJsonObject> failures() const { return loadFromJson<QHash<QString, QJsonObject>>("failures"_ls); } /// One-time keys for the queried devices. A map from user ID, to a - /// map from devices to a map from ``<algorithm>:<key_id>`` to the key - /// object. + /// map from devices to a map from `<algorithm>:<key_id>` to the key object. /// - /// See the `key algorithms <#key-algorithms>`_ section for information - /// on the Key Object format. + /// See the [key algorithms](/client-server-api/#key-algorithms) section for + /// information on the Key Object format. QHash<QString, QHash<QString, QVariant>> oneTimeKeys() const { return loadFromJson<QHash<QString, QHash<QString, QVariant>>>( @@ -190,26 +189,28 @@ public: * The server should include in the results any users who: * * * currently share a room with the calling user (ie, both users have - * membership state ``join``); *and* + * membership state `join`); *and* * * added new device identity keys or removed an existing device with - * identity keys, between ``from`` and ``to``. + * identity keys, between `from` and `to`. */ class GetKeysChangesJob : public BaseJob { public: /*! \brief Query users with recent device key updates. * * \param from - * The desired start point of the list. Should be the ``next_batch`` field - * from a response to an earlier call to |/sync|. Users who have not + * The desired start point of the list. Should be the `next_batch` field + * from a response to an earlier call to + * [`/sync`](/client-server-api/#get_matrixclientr0sync). Users who have not * uploaded new device identity keys since this point, nor deleted * existing devices with identity keys since then, will be excluded * from the results. * * \param to - * The desired end point of the list. Should be the ``next_batch`` - * field from a recent call to |/sync| - typically the most recent - * such call. This may be used by the server as a hint to check its - * caches are up to date. + * The desired end point of the list. Should be the `next_batch` + * field from a recent call to + * [`/sync`](/client-server-api/#get_matrixclientr0sync) - typically the + * most recent such call. This may be used by the server as a hint to check + * its caches are up to date. */ explicit GetKeysChangesJob(const QString& from, const QString& to); diff --git a/lib/csapi/kicking.h b/lib/csapi/kicking.h index 2645a54f..11018368 100644 --- a/lib/csapi/kicking.h +++ b/lib/csapi/kicking.h @@ -15,10 +15,10 @@ namespace Quotient { * The caller must have the required power level in order to perform this * operation. * - * Kicking a user adjusts the target member's membership state to be ``leave`` - * with an optional ``reason``. Like with other membership changes, a user can + * Kicking a user adjusts the target member's membership state to be `leave` + * with an optional `reason`. Like with other membership changes, a user can * directly adjust the target member's state by making a request to - * ``/rooms/<room id>/state/m.room.member/<user id>``. + * `/rooms/<room id>/state/m.room.member/<user id>`. */ class KickJob : public BaseJob { public: @@ -32,7 +32,8 @@ public: * * \param reason * The reason the user has been kicked. This will be supplied as the - * ``reason`` on the target's updated `m.room.member`_ event. + * `reason` on the target's updated + * [`m.room.member`](/client-server-api/#mroommember) event. */ explicit KickJob(const QString& roomId, const QString& userId, const QString& reason = {}); diff --git a/lib/csapi/list_joined_rooms.h b/lib/csapi/list_joined_rooms.h index 1034aa7b..59a24a49 100644 --- a/lib/csapi/list_joined_rooms.h +++ b/lib/csapi/list_joined_rooms.h @@ -26,7 +26,7 @@ public: // Result properties - /// The ID of each room in which the user has ``joined`` membership. + /// The ID of each room in which the user has `joined` membership. QStringList joinedRooms() const { return loadFromJson<QStringList>("joined_rooms"_ls); diff --git a/lib/csapi/list_public_rooms.h b/lib/csapi/list_public_rooms.h index b0cb79d2..963c8b56 100644 --- a/lib/csapi/list_public_rooms.h +++ b/lib/csapi/list_public_rooms.h @@ -170,7 +170,7 @@ public: * * \param thirdPartyInstanceId * The specific third party network/protocol to request from the - * homeserver. Can only be used if ``include_all_networks`` is false. + * homeserver. Can only be used if `include_all_networks` is false. */ explicit QueryPublicRoomsJob(const QString& server = {}, Omittable<int> limit = none, diff --git a/lib/csapi/login.h b/lib/csapi/login.h index a406fc79..b35db1eb 100644 --- a/lib/csapi/login.h +++ b/lib/csapi/login.h @@ -14,17 +14,17 @@ namespace Quotient { /*! \brief Get the supported login types to authenticate users * * Gets the homeserver's supported login types to authenticate users. Clients - * should pick one of these and supply it as the ``type`` when logging in. + * should pick one of these and supply it as the `type` when logging in. */ class GetLoginFlowsJob : public BaseJob { public: // Inner data structures /// Gets the homeserver's supported login types to authenticate users. - /// Clients should pick one of these and supply it as the ``type`` when + /// Clients should pick one of these and supply it as the `type` when /// logging in. struct LoginFlow { - /// The login type. This is supplied as the ``type`` when + /// The login type. This is supplied as the `type` when /// logging in. QString type; }; @@ -64,13 +64,14 @@ struct JsonObjectConverter<GetLoginFlowsJob::LoginFlow> { * Authenticates the user, and issues an access token they can * use to authorize themself in subsequent requests. * - * If the client does not supply a ``device_id``, the server must + * If the client does not supply a `device_id`, the server must * auto-generate one. * - * The returned access token must be associated with the ``device_id`` + * The returned access token must be associated with the `device_id` * supplied by the client or generated by the server. The server may * invalidate any access token previously associated with that device. See - * `Relationship between access tokens and devices`_. + * [Relationship between access tokens and + * devices](/client-server-api/#relationship-between-access-tokens-and-devices). */ class LoginJob : public BaseJob { public: @@ -83,30 +84,33 @@ public: * Authenticates the user, and issues an access token they can * use to authorize themself in subsequent requests. * - * If the client does not supply a ``device_id``, the server must + * If the client does not supply a `device_id`, the server must * auto-generate one. * - * The returned access token must be associated with the ``device_id`` + * The returned access token must be associated with the `device_id` * supplied by the client or generated by the server. The server may * invalidate any access token previously associated with that device. See - * `Relationship between access tokens and devices`_. + * [Relationship between access tokens and + * devices](/client-server-api/#relationship-between-access-tokens-and-devices). * * \param password - * Required when ``type`` is ``m.login.password``. The user's + * Required when `type` is `m.login.password`. The user's * password. * * \param token - * Required when ``type`` is ``m.login.token``. Part of `Token-based`_ - * login. + * Required when `type` is `m.login.token`. Part of Token-based login. * * \param deviceId * ID of the client device. If this does not correspond to a - * known client device, a new device will be created. The server - * will auto-generate a device_id if this is not specified. + * known client device, a new device will be created. The given + * device ID must not be the same as a + * [cross-signing](/client-server-api/#cross-signing) key ID. + * The server will auto-generate a device_id + * if this is not specified. * * \param initialDeviceDisplayName * A display name to assign to the newly-created device. Ignored - * if ``device_id`` corresponds to a known device. + * if `device_id` corresponds to a known device. */ explicit LoginJob(const QString& type, const Omittable<UserIdentifier>& identifier = none, @@ -130,8 +134,8 @@ public: /// been registered. /// /// **Deprecated**. Clients should extract the server_name from - /// ``user_id`` (by splitting at the first colon) if they require - /// it. Note also that ``homeserver`` is not spelt this way. + /// `user_id` (by splitting at the first colon) if they require + /// it. Note also that `homeserver` is not spelt this way. QString homeServer() const { return loadFromJson<QString>("home_server"_ls); diff --git a/lib/csapi/logout.h b/lib/csapi/logout.h index 78f14e40..2e4c2692 100644 --- a/lib/csapi/logout.h +++ b/lib/csapi/logout.h @@ -12,7 +12,8 @@ namespace Quotient { * * Invalidates an existing access token, so that it can no longer be used for * authorization. The device associated with the access token is also deleted. - * `Device keys <#device-keys>`_ for the device are deleted alongside the device. + * [Device keys](/client-server-api/#device-keys) for the device are deleted + * alongside the device. */ class LogoutJob : public BaseJob { public: @@ -31,10 +32,12 @@ public: * * Invalidates all access tokens for a user, so that they can no longer be used * for authorization. This includes the access token that made this request. All - * devices for the user are also deleted. `Device keys <#device-keys>`_ for the - * device are deleted alongside the device. + * devices for the user are also deleted. [Device + * keys](/client-server-api/#device-keys) for the device are deleted alongside + * the device. * - * This endpoint does not use the `User-Interactive Authentication API`_ because + * This endpoint does not use the [User-Interactive Authentication + * API](/client-server-api/#user-interactive-authentication-api) because * User-Interactive Authentication is designed to protect against attacks where * the someone gets hold of a single access token then takes over the account. * This endpoint invalidates all access tokens for the user, including the token diff --git a/lib/csapi/message_pagination.h b/lib/csapi/message_pagination.h index 286d4237..363e4d99 100644 --- a/lib/csapi/message_pagination.h +++ b/lib/csapi/message_pagination.h @@ -15,8 +15,8 @@ namespace Quotient { * pagination query parameters to paginate history in the room. * * *Note*: This endpoint supports lazy-loading of room member events. See - * `Lazy-loading room members <#lazy-loading-room-members>`_ for more - * information. + * [Lazy-loading room members](/client-server-api/#lazy-loading-room-members) + * for more information. */ class GetRoomEventsJob : public BaseJob { public: @@ -27,8 +27,8 @@ public: * * \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 + * 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 @@ -36,8 +36,8 @@ public: * * \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 + * 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 @@ -64,25 +64,25 @@ public: // Result properties - /// The token the pagination starts from. If ``dir=b`` this will be - /// the token supplied in ``from``. + /// The token the pagination starts from. If `dir=b` this will be + /// the token supplied in `from`. QString begin() const { return loadFromJson<QString>("start"_ls); } - /// The token the pagination ends at. If ``dir=b`` this token should + /// The token the pagination ends at. If `dir=b` this token should /// be used again to request even earlier events. QString end() const { return loadFromJson<QString>("end"_ls); } - /// A list of room events. The order depends on the ``dir`` parameter. - /// For ``dir=b`` events will be in reverse-chronological order, - /// for ``dir=f`` in chronological order, so that events start - /// at the ``from`` point. + /// A list of room events. The order depends on the `dir` parameter. + /// For `dir=b` events will be in reverse-chronological order, + /// for `dir=f` in chronological order, so that events start + /// at the `from` point. RoomEvents chunk() { return takeFromJson<RoomEvents>("chunk"_ls); } - /// A list of state events relevant to showing the ``chunk``. For example, if - /// ``lazy_load_members`` is enabled in the filter then this may contain - /// the membership events for the senders of events in the ``chunk``. + /// A list of state events relevant to showing the `chunk`. For example, if + /// `lazy_load_members` is enabled in the filter then this may contain + /// the membership events for the senders of events in the `chunk`. /// - /// Unless ``include_redundant_members`` is ``true``, the server + /// Unless `include_redundant_members` is `true`, the server /// may remove membership events which would have already been /// sent to the client in prior calls to this endpoint, assuming /// the membership of those members has not changed. diff --git a/lib/csapi/notifications.h b/lib/csapi/notifications.h index ff499c7a..0999fece 100644 --- a/lib/csapi/notifications.h +++ b/lib/csapi/notifications.h @@ -22,7 +22,7 @@ public: /// user has been, or would have been notified about. struct Notification { /// The action(s) to perform when the conditions for this rule are met. - /// See `Push Rules: API`_. + /// See [Push Rules: API](/client-server-api/#push-rules-api). QVector<QVariant> actions; /// The Event object for the event that triggered the notification. EventPtr event; @@ -49,7 +49,7 @@ public: * Limit on the number of events to return in this request. * * \param only - * Allows basic filtering of events returned. Supply ``highlight`` + * Allows basic filtering of events returned. Supply `highlight` * to return only events where the notification had the highlight * tweak set. */ @@ -68,8 +68,8 @@ public: // Result properties - /// The token to supply in the ``from`` param of the next - /// ``/notifications`` request in order to request more + /// The token to supply in the `from` param of the next + /// `/notifications` request in order to request more /// events. If this is absent, there are no more results. QString nextToken() const { return loadFromJson<QString>("next_token"_ls); } diff --git a/lib/csapi/openid.h b/lib/csapi/openid.h index efb5f623..0be39c8c 100644 --- a/lib/csapi/openid.h +++ b/lib/csapi/openid.h @@ -18,7 +18,7 @@ namespace Quotient { * OpenID. * * The access token generated is only valid for the OpenID API. It cannot - * be used to request another OpenID access token or call ``/sync``, for + * be used to request another OpenID access token or call `/sync`, for * example. */ class RequestOpenIdTokenJob : public BaseJob { @@ -38,9 +38,10 @@ public: // Result properties /// OpenID token information. This response is nearly compatible with the - /// response documented in the `OpenID Connect 1.0 Specification - /// <http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse>`_ - /// with the only difference being the lack of an ``id_token``. Instead, + /// response documented in the + /// [OpenID Connect 1.0 + /// Specification](http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse) + /// with the only difference being the lack of an `id_token`. Instead, /// the Matrix homeserver's name is provided. OpenidToken tokenData() const { return fromJson<OpenidToken>(jsonData()); } }; diff --git a/lib/csapi/peeking_events.h b/lib/csapi/peeking_events.h index cecd9f2d..885ff340 100644 --- a/lib/csapi/peeking_events.h +++ b/lib/csapi/peeking_events.h @@ -13,12 +13,12 @@ namespace Quotient { * * 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. + * the `timeout` is reached. * - * This API is the same as the normal ``/events`` endpoint, but can be + * 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 + * 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. */ @@ -51,12 +51,12 @@ public: // Result properties - /// A token which correlates to the first value in ``chunk``. This - /// is usually the same token supplied to ``from=``. + /// A token which correlates to the first value in `chunk`. This + /// is usually the same token supplied to `from=`. QString begin() const { return loadFromJson<QString>("start"_ls); } - /// A token which correlates to the last value in ``chunk``. This - /// token should be used in the next request to ``/events``. + /// A token which correlates to the last value in `chunk`. This + /// token should be used in the next request to `/events`. QString end() const { return loadFromJson<QString>("end"_ls); } /// An array of events. diff --git a/lib/csapi/presence.h b/lib/csapi/presence.h index a885bf4f..4ab50e25 100644 --- a/lib/csapi/presence.h +++ b/lib/csapi/presence.h @@ -12,7 +12,7 @@ namespace Quotient { * * This API sets the given user's presence state. When setting the status, * the activity time is updated to reflect that activity; the client does - * not need to specify the ``last_active_ago`` field. You cannot set the + * not need to specify the `last_active_ago` field. You cannot set the * presence state of another user. */ class SetPresenceJob : public BaseJob { diff --git a/lib/csapi/profile.h b/lib/csapi/profile.h index 3858fab2..8bbe4f8c 100644 --- a/lib/csapi/profile.h +++ b/lib/csapi/profile.h @@ -11,7 +11,7 @@ namespace Quotient { /*! \brief Set the user's display name. * * This API sets the given user's display name. You must have permission to - * set this user's display name, e.g. you need to have their ``access_token``. + * set this user's display name, e.g. you need to have their `access_token`. */ class SetDisplayNameJob : public BaseJob { public: @@ -61,7 +61,7 @@ public: /*! \brief Set the user's avatar URL. * * This API sets the given user's avatar URL. You must have permission to - * set this user's avatar URL, e.g. you need to have their ``access_token``. + * set this user's avatar URL, e.g. you need to have their `access_token`. */ class SetAvatarUrlJob : public BaseJob { public: @@ -109,7 +109,7 @@ public: * Get the combined profile information for this user. This API may be used * to fetch the user's own profile information or other users; either * locally or on remote homeservers. This API may return keys which are not - * limited to ``displayname`` or ``avatar_url``. + * limited to `displayname` or `avatar_url`. */ class GetUserProfileJob : public BaseJob { public: diff --git a/lib/csapi/pusher.h b/lib/csapi/pusher.h index ae0050d2..13c9ec25 100644 --- a/lib/csapi/pusher.h +++ b/lib/csapi/pusher.h @@ -19,7 +19,7 @@ public: /// A dictionary of information for the pusher implementation /// itself. struct PusherData { - /// Required if ``kind`` is ``http``. The URL to use to send + /// Required if `kind` is `http`. The URL to use to send /// notifications to. QString url; /// The format to use when sending notifications to the Push @@ -29,11 +29,11 @@ public: /// Gets all currently active pushers for the authenticated user. struct Pusher { - /// This is a unique identifier for this pusher. See ``/set`` for + /// This is a unique identifier for this pusher. See `/set` for /// more detail. /// Max length, 512 bytes. QString pushkey; - /// The kind of pusher. ``"http"`` is a pusher that + /// The kind of pusher. `"http"` is a pusher that /// sends HTTP pokes. QString kind; /// This is a reverse-DNS style identifier for the application. @@ -104,27 +104,27 @@ struct JsonObjectConverter<GetPushersJob::Pusher> { /*! \brief Modify a pusher for this user on the homeserver. * - * This endpoint allows the creation, modification and deletion of `pushers`_ - * for this user ID. The behaviour of this endpoint varies depending on the - * values in the JSON body. + * This endpoint allows the creation, modification and deletion of + * [pushers](/client-server-api/#push-notifications) for this user ID. The + * behaviour of this endpoint varies depending on the values in the JSON body. */ class PostPusherJob : public BaseJob { public: // Inner data structures /// A dictionary of information for the pusher implementation - /// itself. If ``kind`` is ``http``, this should contain ``url`` + /// itself. If `kind` is `http`, this should contain `url` /// which is the URL to use to send notifications to. struct PusherData { - /// Required if ``kind`` is ``http``. The URL to use to send + /// Required if `kind` is `http`. The URL to use to send /// notifications to. MUST be an HTTPS URL with a path of - /// ``/_matrix/push/v1/notify``. + /// `/_matrix/push/v1/notify`. QString url; /// The format to send notifications in to Push Gateways if the - /// ``kind`` is ``http``. The details about what fields the + /// `kind` is `http`. The details about what fields the /// homeserver should send to the push gateway are defined in the - /// `Push Gateway Specification`_. Currently the only format - /// available is 'event_id_only'. + /// [Push Gateway Specification](/push-gateway-api/). Currently the only + /// format available is 'event_id_only'. QString format; }; @@ -140,13 +140,13 @@ public: * client has no such concept, use any unique identifier. * Max length, 512 bytes. * - * If the ``kind`` is ``"email"``, this is the email address to + * If the `kind` is `"email"`, this is the email address to * send notifications to. * * \param kind - * The kind of pusher to configure. ``"http"`` makes a pusher that - * sends HTTP pokes. ``"email"`` makes a pusher that emails the - * user with unread notifications. ``null`` deletes the pusher. + * The kind of pusher to configure. `"http"` makes a pusher that + * sends HTTP pokes. `"email"` makes a pusher that emails the + * user with unread notifications. `null` deletes the pusher. * * \param appId * This is a reverse-DNS style identifier for the application. @@ -154,7 +154,7 @@ public: * different platform versions get different app identifiers. * Max length, 64 chars. * - * If the ``kind`` is ``"email"``, this is ``"m.email"``. + * If the `kind` is `"email"`, this is `"m.email"`. * * \param appDisplayName * A string that will allow the user to identify what application @@ -170,7 +170,7 @@ public: * * \param data * A dictionary of information for the pusher implementation - * itself. If ``kind`` is ``http``, this should contain ``url`` + * itself. If `kind` is `http`, this should contain `url` * which is the URL to use to send notifications to. * * \param profileTag @@ -182,7 +182,7 @@ public: * given pushkey and App ID in addition to any others with * different user IDs. Otherwise, the homeserver must remove any * other pushers with the same App ID and pushkey for different - * users. The default is ``false``. + * users. The default is `false`. */ explicit PostPusherJob(const QString& pushkey, const QString& kind, const QString& appId, const QString& appDisplayName, diff --git a/lib/csapi/pushrules.h b/lib/csapi/pushrules.h index 1c6d5c2d..a5eb48f0 100644 --- a/lib/csapi/pushrules.h +++ b/lib/csapi/pushrules.h @@ -15,9 +15,9 @@ namespace Quotient { /*! \brief Retrieve all push rulesets. * * Retrieve all push rulesets for this user. Clients can "drill-down" on - * the rulesets by suffixing a ``scope`` to this path e.g. - * ``/pushrules/global/``. This will return a subset of this data under the - * specified key e.g. the ``global`` key. + * the rulesets by suffixing a `scope` to this path e.g. + * `/pushrules/global/`. This will return a subset of this data under the + * specified key e.g. the `global` key. */ class GetPushRulesJob : public BaseJob { public: @@ -49,7 +49,7 @@ public: /*! \brief Retrieve a push rule. * * \param scope - * ``global`` to specify global rules. + * `global` to specify global rules. * * \param kind * The kind of rule @@ -71,7 +71,7 @@ public: // Result properties /// The specific push rule. This will also include keys specific to the - /// rule itself such as the rule's ``actions`` and ``conditions`` if set. + /// rule itself such as the rule's `actions` and `conditions` if set. PushRule pushRule() const { return fromJson<PushRule>(jsonData()); } }; @@ -84,7 +84,7 @@ public: /*! \brief Delete a push rule. * * \param scope - * ``global`` to specify global rules. + * `global` to specify global rules. * * \param kind * The kind of rule @@ -117,7 +117,7 @@ public: /*! \brief Add or change a push rule. * * \param scope - * ``global`` to specify global rules. + * `global` to specify global rules. * * \param kind * The kind of rule @@ -129,7 +129,7 @@ public: * The action(s) to perform when the conditions for this rule are met. * * \param before - * Use 'before' with a ``rule_id`` as its value to make the new rule the + * Use 'before' with a `rule_id` as its value to make the new rule the * next-most important rule with respect to the given user defined rule. * It is not possible to add a rule relative to a predefined server rule. * @@ -141,10 +141,10 @@ public: * \param conditions * The conditions that must hold true for an event in order for a * rule to be applied to an event. A rule with no conditions - * always matches. Only applicable to ``underride`` and ``override`` rules. + * always matches. Only applicable to `underride` and `override` rules. * * \param pattern - * Only applicable to ``content`` rules. The glob-style pattern to match + * Only applicable to `content` rules. The glob-style pattern to match * against. */ explicit SetPushRuleJob(const QString& scope, const QString& kind, @@ -165,8 +165,8 @@ public: /*! \brief Get whether a push rule is enabled * * \param scope - * Either ``global`` or ``device/<profile_tag>`` to specify global - * rules or device rules for the given ``profile_tag``. + * Either `global` or `device/<profile_tag>` to specify global + * rules or device rules for the given `profile_tag`. * * \param kind * The kind of rule @@ -200,7 +200,7 @@ public: /*! \brief Enable or disable a push rule. * * \param scope - * ``global`` to specify global rules. + * `global` to specify global rules. * * \param kind * The kind of rule @@ -224,8 +224,8 @@ public: /*! \brief The actions for a push rule * * \param scope - * Either ``global`` or ``device/<profile_tag>`` to specify global - * rules or device rules for the given ``profile_tag``. + * Either `global` or `device/<profile_tag>` to specify global + * rules or device rules for the given `profile_tag`. * * \param kind * The kind of rule @@ -263,7 +263,7 @@ public: /*! \brief Set the actions for a push rule. * * \param scope - * ``global`` to specify global rules. + * `global` to specify global rules. * * \param kind * The kind of rule diff --git a/lib/csapi/read_markers.h b/lib/csapi/read_markers.h index 0e122c63..00a2aa0d 100644 --- a/lib/csapi/read_markers.h +++ b/lib/csapi/read_markers.h @@ -26,7 +26,7 @@ public: * * \param mRead * The event ID to set the read receipt location at. This is - * equivalent to calling ``/receipt/m.read/$elsewhere:example.org`` + * equivalent to calling `/receipt/m.read/$elsewhere:example.org` * and is provided here to save that extra call. */ explicit SetReadMarkerJob(const QString& roomId, const QString& mFullyRead, diff --git a/lib/csapi/receipts.h b/lib/csapi/receipts.h index 1fac0acf..7ac093cd 100644 --- a/lib/csapi/receipts.h +++ b/lib/csapi/receipts.h @@ -27,8 +27,8 @@ public: * The event ID to acknowledge up to. * * \param receipt - * Extra receipt information to attach to ``content`` if any. The - * server will automatically set the ``ts`` field. + * Extra receipt information to attach to `content` if any. The + * server will automatically set the `ts` field. */ explicit PostReceiptJob(const QString& roomId, const QString& receiptType, const QString& eventId, diff --git a/lib/csapi/redaction.h b/lib/csapi/redaction.h index 541e433a..f0db9f9f 100644 --- a/lib/csapi/redaction.h +++ b/lib/csapi/redaction.h @@ -15,9 +15,12 @@ namespace Quotient { * * This cannot be undone. * - * Users may redact their own events, and any user with a power level - * greater than or equal to the ``redact`` power level of the room may - * redact events there. + * Any user with a power level greater than or equal to the `m.room.redaction` + * event power level may send redaction events in the room. If the user's power + * level greater is also greater than or equal to the `redact` power level + * of the room, the user may redact events sent by other users. + * + * Server administrators may redact events sent by users on their server. */ class RedactEventJob : public BaseJob { public: |