Re-generated API files according to the previous commit

Only API-preserving changes are included in this branch (0.7 will have
all changes).

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: