1 files changed, 21 insertions, 17 deletions

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);