Merge branch '0.6.x' into kitsune-fix-read-receipts-and-markers-0.6

19 files changed, 135 insertions, 160 deletions

diff --git a/lib/csapi/definitions/request_email_validation.h b/lib/csapi/definitions/request_email_validation.h
index ab34862e..b1781e27 100644
--- a/lib/csapi/definitions/request_email_validation.h
+++ b/lib/csapi/definitions/request_email_validation.h
@@ -16,15 +16,14 @@ struct EmailValidationData : RequestEmailValidation {
     /// 3PID verification.
     ///
     /// This parameter is deprecated with a plan to be removed in a future
-    /// specification version for ``/account/password`` and ``/register``
-    /// requests.
+    /// specification version for `/account/password` and `/register` requests.
     QString idServer;
 
     /// An access token previously registered with the identity server. Servers
     /// can treat this as optional to distinguish between r0.5-compatible
     /// clients and this specification version.
     ///
-    /// Required if an ``id_server`` is supplied.
+    /// Required if an `id_server` is supplied.
     QString idAccessToken;
 };
 
diff --git a/lib/csapi/definitions/request_msisdn_validation.h b/lib/csapi/definitions/request_msisdn_validation.h
index 8539cd98..4600b48c 100644
--- a/lib/csapi/definitions/request_msisdn_validation.h
+++ b/lib/csapi/definitions/request_msisdn_validation.h
@@ -16,15 +16,14 @@ struct MsisdnValidationData : RequestMsisdnValidation {
     /// 3PID verification.
     ///
     /// This parameter is deprecated with a plan to be removed in a future
-    /// specification version for ``/account/password`` and ``/register``
-    /// requests.
+    /// specification version for `/account/password` and `/register` requests.
     QString idServer;
 
     /// An access token previously registered with the identity server. Servers
     /// can treat this as optional to distinguish between r0.5-compatible
     /// clients and this specification version.
     ///
-    /// Required if an ``id_server`` is supplied.
+    /// Required if an `id_server` is supplied.
     QString idAccessToken;
 };
 
diff --git a/lib/csapi/definitions/request_token_response.h b/lib/csapi/definitions/request_token_response.h
index 00222839..f9981100 100644
--- a/lib/csapi/definitions/request_token_response.h
+++ b/lib/csapi/definitions/request_token_response.h
@@ -10,20 +10,20 @@ namespace Quotient {
 
 struct RequestTokenResponse {
     /// The session ID. Session IDs are opaque strings that must consist
-    /// entirely of the characters ``[0-9a-zA-Z.=_-]``. Their length must not
+    /// entirely of the characters `[0-9a-zA-Z.=_-]`. Their length must not
     /// exceed 255 characters and they must not be empty.
     QString sid;
 
     /// An optional field containing a URL where the client must submit the
     /// validation token to, with identical parameters to the Identity Service
-    /// API's ``POST /validate/email/submitToken`` endpoint (without the
+    /// API's `POST /validate/email/submitToken` endpoint (without the
     /// requirement for an access token). The homeserver must send this token to
     /// the user (if applicable), who should then be prompted to provide it to
     /// the client.
     ///
     /// If this field is not present, the client can assume that verification
     /// will happen without the client's involvement provided the homeserver
-    /// advertises this specification version in the ``/versions`` response
+    /// advertises this specification version in the `/versions` response
     /// (ie: r0.5.0).
     QString submitUrl;
 };
diff --git a/lib/csapi/definitions/room_event_filter.h b/lib/csapi/definitions/room_event_filter.h
index 11e87fde..91caf667 100644
--- a/lib/csapi/definitions/room_event_filter.h
+++ b/lib/csapi/definitions/room_event_filter.h
@@ -11,30 +11,31 @@
 namespace Quotient {
 
 struct RoomEventFilter : EventFilter {
-    /// If ``true``, enables lazy-loading of membership events. See
-    /// `Lazy-loading room members <#lazy-loading-room-members>`_
-    /// for more information. Defaults to ``false``.
+    /// If `true`, enables lazy-loading of membership events. See
+    /// [Lazy-loading room
+    /// members](/client-server-api/#lazy-loading-room-members) for more
+    /// information. Defaults to `false`.
     Omittable<bool> lazyLoadMembers;
 
-    /// If ``true``, sends all membership events for all events, even if they
-    /// have already been sent to the client. Does not apply unless
-    /// ``lazy_load_members`` is ``true``. See `Lazy-loading room members
-    /// <#lazy-loading-room-members>`_ for more information. Defaults to
-    /// ``false``.
+    /// If `true`, sends all membership events for all events, even if they have
+    /// already been sent to the client. Does not apply unless
+    /// `lazy_load_members` is `true`. See [Lazy-loading room
+    /// members](/client-server-api/#lazy-loading-room-members) for more
+    /// information. Defaults to `false`.
     Omittable<bool> includeRedundantMembers;
 
     /// A list of room IDs to exclude. If this list is absent then no rooms are
     /// excluded. A matching room will be excluded even if it is listed in the
-    /// ``'rooms'`` filter.
+    /// `'rooms'` filter.
     QStringList notRooms;
 
     /// A list of room IDs to include. If this list is absent then all rooms are
     /// included.
     QStringList rooms;
 
-    /// If ``true``, includes only events with a ``url`` key in their content.
-    /// If ``false``, excludes those events. If omitted, ``url`` key is not
-    /// considered for filtering.
+    /// If `true`, includes only events with a `url` key in their content. If
+    /// `false`, excludes those events. If omitted, `url` key is not considered
+    /// for filtering.
     Omittable<bool> containsUrl;
 };
 
diff --git a/lib/csapi/definitions/sync_filter.h b/lib/csapi/definitions/sync_filter.h
index 9c8f08d5..62e17962 100644
--- a/lib/csapi/definitions/sync_filter.h
+++ b/lib/csapi/definitions/sync_filter.h
@@ -14,13 +14,13 @@ namespace Quotient {
 struct RoomFilter {
     /// A list of room IDs to exclude. If this list is absent then no rooms are
     /// excluded. A matching room will be excluded even if it is listed in the
-    /// ``'rooms'`` filter. This filter is applied before the filters in
-    /// ``ephemeral``, ``state``, ``timeline`` or ``account_data``
+    /// `'rooms'` filter. This filter is applied before the filters in
+    /// `ephemeral`, `state`, `timeline` or `account_data`
     QStringList notRooms;
 
     /// A list of room IDs to include. If this list is absent then all rooms are
-    /// included. This filter is applied before the filters in ``ephemeral``,
-    /// ``state``, ``timeline`` or ``account_data``
+    /// included. This filter is applied before the filters in `ephemeral`,
+    /// `state`, `timeline` or `account_data`
     QStringList rooms;
 
     /// The events that aren't recorded in the room history, e.g. typing and
diff --git a/lib/csapi/definitions/third_party_signed.h b/lib/csapi/definitions/third_party_signed.h
index 526545d0..7097bda4 100644
--- a/lib/csapi/definitions/third_party_signed.h
+++ b/lib/csapi/definitions/third_party_signed.h
@@ -7,7 +7,7 @@
 #include "converters.h"
 
 namespace Quotient {
-/// A signature of an ``m.third_party_invite`` token to prove that this user
+/// A signature of an `m.third_party_invite` token to prove that this user
 /// owns a third party identity which has been invited to the room.
 struct ThirdPartySigned {
     /// The Matrix ID of the user who issued the invite.
diff --git a/lib/csapi/definitions/user_identifier.h b/lib/csapi/definitions/user_identifier.h
index dadf6f97..cb585a6a 100644
--- a/lib/csapi/definitions/user_identifier.h
+++ b/lib/csapi/definitions/user_identifier.h
@@ -9,8 +9,9 @@
 namespace Quotient {
 /// Identification information for a user
 struct UserIdentifier {
-    /// The type of identification.  See `Identifier types`_ for supported
-    /// values and additional property descriptions.
+    /// The type of identification.  See [Identifier
+    /// types](/client-server-api/#identifier-types) for supported values and
+    /// additional property descriptions.
     QString type;
 
     /// Identification information for a user
diff --git a/lib/csapi/registration.h b/lib/csapi/registration.h
index 62bc35f1..ae8fc162 100644
--- a/lib/csapi/registration.h
+++ b/lib/csapi/registration.h
@@ -15,8 +15,9 @@ namespace Quotient {
 
 /*! \brief Register for an account on this homeserver.
  *
- * This API endpoint uses the `User-Interactive Authentication API`_, except in
- * the cases where a guest account is being registered.
+ * This API endpoint uses the [User-Interactive Authentication
+ * API](/client-server-api/#user-interactive-authentication-api), except in the
+ * cases where a guest account is being registered.
  *
  * Register for an account on this homeserver.
  *
@@ -31,45 +32,46 @@ namespace Quotient {
  * If registration is successful, this endpoint will issue an access token
  * the client can use to authorize itself 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 server SHOULD register an account with a User ID based on the
- * ``username`` provided, if any. Note that the grammar of Matrix User ID
+ * `username` provided, if any. Note that the grammar of Matrix User ID
  * localparts is restricted, so the server MUST either map the provided
- * ``username`` onto a ``user_id`` in a logical manner, or reject
- * ``username``\s which do not comply to the grammar, with
- * ``M_INVALID_USERNAME``.
+ * `username` onto a `user_id` in a logical manner, or reject
+ * `username`\s which do not comply to the grammar, with
+ * `M_INVALID_USERNAME`.
  *
  * Matrix clients MUST NOT assume that localpart of the registered
- * ``user_id`` matches the provided ``username``.
+ * `user_id` matches the provided `username`.
  *
- * 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).
  *
  * When registering a guest account, all parameters in the request body
- * with the exception of ``initial_device_display_name`` MUST BE ignored
- * by the server. The server MUST pick a ``device_id`` for the account
+ * with the exception of `initial_device_display_name` MUST BE ignored
+ * by the server. The server MUST pick a `device_id` for the account
  * regardless of input.
  *
  * Any user ID returned by this API must conform to the grammar given in the
- * `Matrix specification <../appendices.html#user-identifiers>`_.
+ * [Matrix specification](/appendices/#user-identifiers).
  */
 class RegisterJob : public BaseJob {
 public:
     /*! \brief Register for an account on this homeserver.
      *
      * \param kind
-     *   The kind of account to register. Defaults to ``user``.
+     *   The kind of account to register. Defaults to `user`.
      *
      * \param auth
      *   Additional authentication information for the
      *   user-interactive authentication API. Note that this
      *   information is *not* used to define how the registered user
      *   should be authenticated, but is instead used to
-     *   authenticate the ``register`` call itself.
+     *   authenticate the `register` call itself.
      *
      * \param username
      *   The basis for the localpart of the desired Matrix ID. If omitted,
@@ -85,10 +87,10 @@ public:
      *
      * \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.
      *
      * \param inhibitLogin
-     *   If true, an ``access_token`` and ``device_id`` should not be
+     *   If true, an `access_token` and `device_id` should not be
      *   returned from this call, therefore preventing an automatic
      *   login. Defaults to false.
      */
@@ -105,12 +107,12 @@ public:
     /// The fully-qualified Matrix user ID (MXID) that has been registered.
     ///
     /// Any user ID returned by this API must conform to the grammar given in
-    /// the `Matrix specification <../appendices.html#user-identifiers>`_.
+    /// the [Matrix specification](/appendices/#user-identifiers).
     QString userId() const { return loadFromJson<QString>("user_id"_ls); }
 
     /// An access token for the account.
     /// This access token can then be used to authorize other requests.
-    /// Required if the ``inhibit_login`` option is false.
+    /// Required if the `inhibit_login` option is false.
     QString accessToken() const
     {
         return loadFromJson<QString>("access_token"_ls);
@@ -120,8 +122,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);
@@ -129,7 +131,7 @@ public:
 
     /// ID of the registered device. Will be the same as the
     /// corresponding parameter in the request, if one was specified.
-    /// Required if the ``inhibit_login`` option is false.
+    /// Required if the `inhibit_login` option is false.
     QString deviceId() const { return loadFromJson<QString>("device_id"_ls); }
 };
 
@@ -201,9 +203,9 @@ public:
  *
  * Changes the password for an account on this homeserver.
  *
- * This API endpoint uses the `User-Interactive Authentication API`_ to
- * ensure the user changing the password is actually the owner of the
- * account.
+ * This API endpoint uses the [User-Interactive Authentication
+ * API](/client-server-api/#user-interactive-authentication-api) to ensure the
+ * user changing the password is actually the owner of the account.
  *
  * An access token should be submitted to this endpoint if the client has
  * an active session.
@@ -222,10 +224,10 @@ public:
      *
      * \param logoutDevices
      *   Whether the user's other access tokens, and their associated devices,
-     * should be revoked if the request succeeds. Defaults to true.
+     * should be revoked if the request succeeds.
      *
-     *   When ``false``, the server can still take advantage of `the soft logout
-     * method <#soft-logout>`_ for the user's remaining devices.
+     *   When `false`, the server can still take advantage of the [soft logout
+     * method](/client-server-api/#soft-logout) for the user's remaining devices.
      *
      * \param auth
      *   Additional authentication information for the user-interactive
@@ -242,23 +244,18 @@ public:
  * The homeserver must check that the given email address **is
  * associated** with an account on this homeserver. This API should be
  * used to request validation tokens when authenticating for the
- * ``/account/password`` endpoint.
+ * `/account/password` endpoint.
  *
  * This API's parameters and response are identical to that of the
- * |/register/email/requestToken|_ endpoint, except that
- * ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
+ * [`/register/email/requestToken`](/client-server-api/#post_matrixclientr0registeremailrequesttoken)
+ * endpoint, except that
+ * `M_THREEPID_NOT_FOUND` may be returned if no account matching the
  * given email address could be found. The server may instead send an
  * email to the given address prompting the user to create an account.
- * ``M_THREEPID_IN_USE`` may not be returned.
+ * `M_THREEPID_IN_USE` may not be returned.
  *
  * The homeserver should validate the email itself, either by sending a
  * validation email itself or by using a service it has control over.
- *
- *
- * .. |/register/email/requestToken| replace:: ``/register/email/requestToken``
- *
- * .. _/register/email/requestToken:
- * #post-matrix-client-r0-register-email-requesttoken
  */
 class RequestTokenToResetPasswordEmailJob : public BaseJob {
 public:
@@ -269,24 +266,18 @@ public:
      *   The homeserver must check that the given email address **is
      *   associated** with an account on this homeserver. This API should be
      *   used to request validation tokens when authenticating for the
-     *   ``/account/password`` endpoint.
+     *   `/account/password` endpoint.
      *
      *   This API's parameters and response are identical to that of the
-     *   |/register/email/requestToken|_ endpoint, except that
-     *   ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
+     *   [`/register/email/requestToken`](/client-server-api/#post_matrixclientr0registeremailrequesttoken)
+     *   endpoint, except that
+     *   `M_THREEPID_NOT_FOUND` may be returned if no account matching the
      *   given email address could be found. The server may instead send an
      *   email to the given address prompting the user to create an account.
-     *   ``M_THREEPID_IN_USE`` may not be returned.
+     *   `M_THREEPID_IN_USE` may not be returned.
      *
      *   The homeserver should validate the email itself, either by sending a
      *   validation email itself or by using a service it has control over.
-     *
-     *
-     *   .. |/register/email/requestToken| replace::
-     * ``/register/email/requestToken``
-     *
-     *   .. _/register/email/requestToken:
-     * #post-matrix-client-r0-register-email-requesttoken
      */
     explicit RequestTokenToResetPasswordEmailJob(const EmailValidationData& body);
 
@@ -305,22 +296,18 @@ public:
  * The homeserver must check that the given phone number **is
  * associated** with an account on this homeserver. This API should be
  * used to request validation tokens when authenticating for the
- * ``/account/password`` endpoint.
+ * `/account/password` endpoint.
  *
  * This API's parameters and response are identical to that of the
- * |/register/msisdn/requestToken|_ endpoint, except that
- * ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
+ * [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientr0registermsisdnrequesttoken)
+ * endpoint, except that
+ * `M_THREEPID_NOT_FOUND` may be returned if no account matching the
  * given phone number could be found. The server may instead send the SMS
  * to the given phone number prompting the user to create an account.
- * ``M_THREEPID_IN_USE`` may not be returned.
+ * `M_THREEPID_IN_USE` may not be returned.
  *
  * The homeserver should validate the phone number itself, either by sending a
  * validation message itself or by using a service it has control over.
- *
- * .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken``
- *
- * .. _/register/msisdn/requestToken:
- * #post-matrix-client-r0-register-email-requesttoken
  */
 class RequestTokenToResetPasswordMSISDNJob : public BaseJob {
 public:
@@ -331,23 +318,18 @@ public:
      *   The homeserver must check that the given phone number **is
      *   associated** with an account on this homeserver. This API should be
      *   used to request validation tokens when authenticating for the
-     *   ``/account/password`` endpoint.
+     *   `/account/password` endpoint.
      *
      *   This API's parameters and response are identical to that of the
-     *   |/register/msisdn/requestToken|_ endpoint, except that
-     *   ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
+     *   [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientr0registermsisdnrequesttoken)
+     *   endpoint, except that
+     *   `M_THREEPID_NOT_FOUND` may be returned if no account matching the
      *   given phone number could be found. The server may instead send the SMS
      *   to the given phone number prompting the user to create an account.
-     *   ``M_THREEPID_IN_USE`` may not be returned.
+     *   `M_THREEPID_IN_USE` may not be returned.
      *
      *   The homeserver should validate the phone number itself, either by sending
      * a validation message itself or by using a service it has control over.
-     *
-     *   .. |/register/msisdn/requestToken| replace::
-     * ``/register/msisdn/requestToken``
-     *
-     *   .. _/register/msisdn/requestToken:
-     * #post-matrix-client-r0-register-email-requesttoken
      */
     explicit RequestTokenToResetPasswordMSISDNJob(
         const MsisdnValidationData& body);
@@ -366,7 +348,8 @@ public:
  * Deactivate the user's account, removing all ability for the user to
  * login again.
  *
- * 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).
  *
  * An access token should be submitted to this endpoint if the client has
  * an active session.
@@ -374,7 +357,7 @@ public:
  * The homeserver may change the flows available depending on whether a
  * valid access token is provided.
  *
- * 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.
  */
@@ -388,11 +371,11 @@ public:
      *
      * \param idServer
      *   The identity server to unbind all of the user's 3PIDs from.
-     *   If not provided, the homeserver MUST use the ``id_server``
+     *   If not provided, the homeserver MUST use the `id_server`
      *   that was originally use to bind each identifier. If the
-     *   homeserver does not know which ``id_server`` that was,
-     *   it must return an ``id_server_unbind_result`` of
-     *   ``no-support``.
+     *   homeserver does not know which `id_server` that was,
+     *   it must return an `id_server_unbind_result` of
+     *   `no-support`.
      */
     explicit DeactivateAccountJob(const Omittable<AuthenticationData>& auth = none,
                                   const QString& idServer = {});
@@ -400,12 +383,12 @@ public:
     // Result properties
 
     /// An indicator as to whether or not the homeserver was able to unbind
-    /// the user's 3PIDs from the identity server(s). ``success`` indicates
+    /// the user's 3PIDs from the identity server(s). `success` indicates
     /// that all identifiers have been unbound from the identity server while
-    /// ``no-support`` indicates that one or more identifiers failed to unbind
+    /// `no-support` indicates that one or more identifiers failed to unbind
     /// due to the identity server refusing the request or the homeserver
     /// being unable to determine an identity server to unbind from. This
-    /// must be ``success`` if the homeserver has no identifiers to unbind
+    /// must be `success` if the homeserver has no identifiers to unbind
     /// for the user.
     QString idServerUnbindResult() const
     {
@@ -447,7 +430,7 @@ public:
     // Result properties
 
     /// A flag to indicate that the username is available. This should always
-    /// be ``true`` when the server replies with 200 OK.
+    /// be `true` when the server replies with 200 OK.
     Omittable<bool> available() const
     {
         return loadFromJson<Omittable<bool>>("available"_ls);
diff --git a/lib/csapi/room_send.h b/lib/csapi/room_send.h
index 39460aca..96f5beca 100644
--- a/lib/csapi/room_send.h
+++ b/lib/csapi/room_send.h
@@ -16,7 +16,7 @@ namespace Quotient {
  *
  * The body of the request should be the content object of the event; the
  * fields in this object will vary depending on the type of event. See
- * `Room Events`_ for the m. event specification.
+ * [Room Events](/client-server-api/#room-events) for the m. event specification.
  */
 class SendMessageJob : public BaseJob {
 public:
@@ -40,7 +40,8 @@ public:
      *
      *   The body of the request should be the content object of the event; the
      *   fields in this object will vary depending on the type of event. See
-     *   `Room Events`_ for the m. event specification.
+     *   [Room Events](/client-server-api/#room-events) for the m. event
+     * specification.
      */
     explicit SendMessageJob(const QString& roomId, const QString& eventType,
                             const QString& txnId, const QJsonObject& body = {});
diff --git a/lib/csapi/room_state.h b/lib/csapi/room_state.h
index 447605ff..f95af223 100644
--- a/lib/csapi/room_state.h
+++ b/lib/csapi/room_state.h
@@ -10,22 +10,20 @@ namespace Quotient {
 
 /*! \brief Send a state event to the given room.
  *
- * .. For backwards compatibility with older links...
- * .. _`put-matrix-client-r0-rooms-roomid-state-eventtype`:
- *
  * State events can be sent using this endpoint.  These events will be
- * overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
+ * overwritten if `<room id>`, `<event type>` and `<state key>` all
  * match.
  *
  * Requests to this endpoint **cannot use transaction IDs**
- * like other ``PUT`` paths because they cannot be differentiated from the
- * ``state_key``. Furthermore, ``POST`` is unsupported on state paths.
+ * like other `PUT` paths because they cannot be differentiated from the
+ * `state_key`. Furthermore, `POST` is unsupported on state paths.
  *
  * The body of the request should be the content object of the event; the
  * fields in this object will vary depending on the type of event. See
- * `Room Events`_ for the ``m.`` event specification.
+ * [Room Events](/client-server-api/#room-events) for the `m.` event
+ * specification.
  *
- * If the event type being sent is ``m.room.canonical_alias`` servers
+ * If the event type being sent is `m.room.canonical_alias` servers
  * SHOULD ensure that any new aliases being listed in the event are valid
  * per their grammar/syntax and that they point to the room ID where the
  * state event is to be sent. Servers do not validate aliases which are
@@ -46,22 +44,20 @@ public:
      *   an empty string, the trailing slash on this endpoint is optional.
      *
      * \param body
-     *   .. For backwards compatibility with older links...
-     *   .. _`put-matrix-client-r0-rooms-roomid-state-eventtype`:
-     *
      *   State events can be sent using this endpoint.  These events will be
-     *   overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
+     *   overwritten if `<room id>`, `<event type>` and `<state key>` all
      *   match.
      *
      *   Requests to this endpoint **cannot use transaction IDs**
-     *   like other ``PUT`` paths because they cannot be differentiated from the
-     *   ``state_key``. Furthermore, ``POST`` is unsupported on state paths.
+     *   like other `PUT` paths because they cannot be differentiated from the
+     *   `state_key`. Furthermore, `POST` is unsupported on state paths.
      *
      *   The body of the request should be the content object of the event; the
      *   fields in this object will vary depending on the type of event. See
-     *   `Room Events`_ for the ``m.`` event specification.
+     *   [Room Events](/client-server-api/#room-events) for the `m.` event
+     * specification.
      *
-     *   If the event type being sent is ``m.room.canonical_alias`` servers
+     *   If the event type being sent is `m.room.canonical_alias` servers
      *   SHOULD ensure that any new aliases being listed in the event are valid
      *   per their grammar/syntax and that they point to the room ID where the
      *   state event is to be sent. Servers do not validate aliases which are
diff --git a/lib/csapi/rooms.h b/lib/csapi/rooms.h
index f0bfa349..51af2c65 100644
--- a/lib/csapi/rooms.h
+++ b/lib/csapi/rooms.h
@@ -12,7 +12,7 @@ namespace Quotient {
 
 /*! \brief Get a single event by event ID.
  *
- * Get a single event based on ``roomId/eventId``. You must have permission to
+ * Get a single event based on `roomId/eventId`. You must have permission to
  * retrieve this event e.g. by being a member in the room for this event.
  */
 class GetOneRoomEventJob : public BaseJob {
@@ -43,9 +43,6 @@ public:
 
 /*! \brief Get the state identified by the type and key.
  *
- * .. For backwards compatibility with older links...
- * .. _`get-matrix-client-r0-rooms-roomid-state-eventtype`:
- *
  * Looks up the contents of a state event in a room. If the user is
  * joined to the room then the state is taken from the current
  * state of the room. If the user has left the room then the state is
@@ -118,16 +115,15 @@ public:
      *
      * \param at
      *   The point in time (pagination token) to return members for in the room.
-     *   This token can be obtained from a ``prev_batch`` token returned for
+     *   This token can be obtained from a `prev_batch` token returned for
      *   each room by the sync API. Defaults to the current state of the room,
      *   as determined by the server.
      *
      * \param membership
      *   The kind of membership to filter for. Defaults to no filtering if
-     *   unspecified. When specified alongside ``not_membership``, the two
+     *   unspecified. When specified alongside `not_membership`, the two
      *   parameters create an 'or' condition: either the membership *is*
-     *   the same as ``membership`` **or** *is not* the same as
-     * ``not_membership``.
+     *   the same as `membership` **or** *is not* the same as `not_membership`.
      *
      * \param notMembership
      *   The kind of membership to exclude from the results. Defaults to no
@@ -162,7 +158,7 @@ public:
  * room. The current user must be in the room for it to work, unless it is an
  * Application Service in which case any of the AS's users must be in the room.
  * This API is primarily for Application Services and should be faster to
- * respond than ``/members`` as it can be implemented more efficiently on the
+ * respond than `/members` as it can be implemented more efficiently on the
  * server.
  */
 class GetJoinedMembersByRoomJob : public BaseJob {
@@ -173,7 +169,7 @@ public:
     /// the room. The current user must be in the room for it to work, unless it
     /// is an Application Service in which case any of the AS's users must be in
     /// the room. This API is primarily for Application Services and should be
-    /// faster to respond than ``/members`` as it can be implemented more
+    /// faster to respond than `/members` as it can be implemented more
     /// efficiently on the server.
     struct RoomMember {
         /// The display name of the user this object is representing.
diff --git a/lib/csapi/sso_login_redirect.h b/lib/csapi/sso_login_redirect.h
index d6330e38..6205ca59 100644
--- a/lib/csapi/sso_login_redirect.h
+++ b/lib/csapi/sso_login_redirect.h
@@ -13,7 +13,9 @@ namespace Quotient {
  * A web-based Matrix client should instruct the user's browser to
  * navigate to this endpoint in order to log in via SSO.
  *
- * The server MUST respond with an HTTP redirect to the SSO interface.
+ * The server MUST respond with an HTTP redirect to the SSO interface,
+ * or present a page which lets the user select an IdP to continue
+ * with in the event multiple are supported by the server.
  */
 class RedirectToSSOJob : public BaseJob {
 public:
diff --git a/lib/csapi/tags.h b/lib/csapi/tags.h
index a815d9b3..a854531a 100644
--- a/lib/csapi/tags.h
+++ b/lib/csapi/tags.h
@@ -18,7 +18,7 @@ public:
 
     /// List the tags set by a user on a room.
     struct Tag {
-        /// A number in a range ``[0,1]`` describing a relative
+        /// A number in a range `[0,1]` describing a relative
         /// position of the room under the given tag.
         Omittable<float> order;
         /// List the tags set by a user on a room.
@@ -83,7 +83,7 @@ public:
      *   The tag to add.
      *
      * \param order
-     *   A number in a range ``[0,1]`` describing a relative
+     *   A number in a range `[0,1]` describing a relative
      *   position of the room under the given tag.
      *
      * \param additionalProperties
diff --git a/lib/csapi/third_party_membership.h b/lib/csapi/third_party_membership.h
index 55cab370..a424678f 100644
--- a/lib/csapi/third_party_membership.h
+++ b/lib/csapi/third_party_membership.h
@@ -10,14 +10,13 @@ namespace Quotient {
 
 /*! \brief Invite a user to participate in a particular room.
  *
- * .. _invite-by-third-party-id-endpoint:
- *
  * *Note that there are two forms of this API, which are documented separately.
  * This version of the API does not require that the inviter know the Matrix
  * identifier of the invitee, and instead relies on third party identifiers.
  * The homeserver uses an identity server to perform the mapping from
  * third party identifier to a Matrix identifier. The other is documented in
- * the* `joining rooms section`_.
+ * the* [joining rooms
+ * section](/client-server-api/#post_matrixclientr0roomsroomidinvite).
  *
  * This API invites a user to participate in a particular room.
  * They do not start participating in the room until they actually join the
@@ -27,7 +26,7 @@ namespace Quotient {
  * join that room.
  *
  * If the identity server did know the Matrix user identifier for the
- * third party identifier, the homeserver will append a ``m.room.member``
+ * third party identifier, the homeserver will append a `m.room.member`
  * event to the room.
  *
  * If the identity server does not know a Matrix user identifier for the
@@ -35,7 +34,7 @@ namespace Quotient {
  * which can be accepted upon providing proof of ownership of the third
  * party identifier. This is achieved by the identity server generating a
  * token, which it gives to the inviting homeserver. The homeserver will
- * add an ``m.room.third_party_invite`` event into the graph for the room,
+ * add an `m.room.third_party_invite` event into the graph for the room,
  * containing that token.
  *
  * When the invitee binds the invited third party identifier to a Matrix
@@ -51,9 +50,7 @@ namespace Quotient {
  * - The matrix user ID who invited them to the room
  *
  * If a token is requested from the identity server, the homeserver will
- * append a ``m.room.third_party_invite`` event to the room.
- *
- * .. _joining rooms section: `invite-by-user-id-endpoint`_
+ * append a `m.room.third_party_invite` event to the room.
  */
 class InviteBy3PIDJob : public BaseJob {
 public:
@@ -73,7 +70,7 @@ public:
      *
      * \param medium
      *   The kind of address being passed in the address field, for example
-     * ``email``.
+     * `email`.
      *
      * \param address
      *   The invitee's third party identifier.
diff --git a/lib/csapi/typing.h b/lib/csapi/typing.h
index 2c953949..64a310d0 100644
--- a/lib/csapi/typing.h
+++ b/lib/csapi/typing.h
@@ -11,8 +11,8 @@ namespace Quotient {
 /*! \brief Informs the server that the user has started or stopped typing.
  *
  * This tells the server that the user is typing for the next N
- * milliseconds where N is the value specified in the ``timeout`` key.
- * Alternatively, if ``typing`` is ``false``, it tells the server that the
+ * milliseconds where N is the value specified in the `timeout` key.
+ * Alternatively, if `typing` is `false`, it tells the server that the
  * user has stopped typing.
  */
 class SetTypingJob : public BaseJob {
@@ -26,7 +26,7 @@ public:
      *   The room in which the user is typing.
      *
      * \param typing
-     *   Whether the user is typing or not. If ``false``, the ``timeout``
+     *   Whether the user is typing or not. If `false`, the `timeout`
      *   key can be omitted.
      *
      * \param timeout
diff --git a/lib/csapi/users.h b/lib/csapi/users.h
index 6fc26f57..eab18f6c 100644
--- a/lib/csapi/users.h
+++ b/lib/csapi/users.h
@@ -19,7 +19,7 @@ namespace Quotient {
  *
  * The search is performed case-insensitively on user IDs and display
  * names preferably using a collation determined based upon the
- * ``Accept-Language`` header provided in the request, if present.
+ * `Accept-Language` header provided in the request, if present.
  */
 class SearchUserDirectoryJob : public BaseJob {
 public:
@@ -34,7 +34,7 @@ public:
     ///
     /// The search is performed case-insensitively on user IDs and display
     /// names preferably using a collation determined based upon the
-    /// ``Accept-Language`` header provided in the request, if present.
+    /// `Accept-Language` header provided in the request, if present.
     struct User {
         /// The user's matrix user ID.
         QString userId;
diff --git a/lib/csapi/versions.h b/lib/csapi/versions.h
index 828a7eb9..896e2ea9 100644
--- a/lib/csapi/versions.h
+++ b/lib/csapi/versions.h
@@ -12,14 +12,14 @@ namespace Quotient {
  *
  * Gets the versions of the specification supported by the server.
  *
- * Values will take the form ``rX.Y.Z``.
+ * Values will take the form `rX.Y.Z`.
  *
- * Only the latest ``Z`` value will be reported for each supported ``X.Y``
- * value. i.e. if the server implements ``r0.0.0``, ``r0.0.1``, and ``r1.2.0``,
- * it will report ``r0.0.1`` and ``r1.2.0``.
+ * Only the latest `Z` value will be reported for each supported `X.Y` value.
+ * i.e. if the server implements `r0.0.0`, `r0.0.1`, and `r1.2.0`, it will
+ * report `r0.0.1` and `r1.2.0`.
  *
  * The server may additionally advertise experimental features it supports
- * through ``unstable_features``. These features should be namespaced and
+ * through `unstable_features`. These features should be namespaced and
  * may optionally include version information within their name if desired.
  * Features listed here are not for optionally toggling parts of the Matrix
  * specification and should only be used to advertise support for a feature
diff --git a/lib/csapi/wellknown.h b/lib/csapi/wellknown.h
index b21d9fc7..c707d232 100644
--- a/lib/csapi/wellknown.h
+++ b/lib/csapi/wellknown.h
@@ -14,7 +14,7 @@ namespace Quotient {
  *
  * Gets discovery information about the domain. The file may include
  * additional keys, which MUST follow the Java package naming convention,
- * e.g. ``com.example.myapp.property``. This ensures property names are
+ * e.g. `com.example.myapp.property`. This ensures property names are
  * suitably namespaced for each application and reduces the risk of
  * clashes.
  *
diff --git a/lib/csapi/whoami.h b/lib/csapi/whoami.h
index af8f1e8a..184459ea 100644
--- a/lib/csapi/whoami.h
+++ b/lib/csapi/whoami.h
@@ -14,8 +14,8 @@ namespace Quotient {
  *
  * Note that, as with the rest of the Client-Server API,
  * Application Services may masquerade as users within their
- * namespace by giving a ``user_id`` query parameter. In this
- * situation, the server should verify that the given ``user_id``
+ * namespace by giving a `user_id` query parameter. In this
+ * situation, the server should verify that the given `user_id`
  * is registered by the appservice, and return it in the response
  * body.
  */
@@ -33,7 +33,7 @@ public:
 
     // Result properties
 
-    /// The user id that owns the access token.
+    /// The user ID that owns the access token.
     QString userId() const { return loadFromJson<QString>("user_id"_ls); }
 };