Apply suggestions

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

content/client-server-api/_index.md

@@ -482,9 +482,9 @@ such as automated applications that cannot use a web browser.
 
 {{% boxes/note %}}
 {{% added-in v="1.18" %}}
-A compatibility layer is available to ease the transition from the legacy API to
+A compatibility feature, called [OAuth 2.0 aware clients](#oauth-20-aware-clients),
-the OAuth 2.0 API for clients that only support the legacy API called [OAuth 2.0
+is available to ease the transition to the OAuth 2.0 API for clients that only
-aware clients](#oauth-20-aware-clients).
+support the legacy API.
 {{% /boxes/note %}}
 
 ### Authentication API discovery
@@ -1525,11 +1525,6 @@ client supports it, the client should redirect the user to the
 is complete, the client will need to submit a `/login` request matching
 `m.login.token`.
 
-{{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
-MUST only offer the `m.login.sso` flow to the user when `oauth_aware_preferred`
-is set to `true` and MUST add the `action=login` parameter to the SSO redirect
-endpoint.
-
 {{% added-in v="1.7" %}} Already-authenticated clients can additionally generate
 a token for their user ID if supported by the homeserver using
 [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token).
@@ -1628,10 +1623,11 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
 
 {{% added-in v="1.18" %}}
 
-This is a compatibility layer that allows clients that only support the legacy
+This is a compatibility feature to aide clients in the transition to the OAuth
-API to make some less-invasive changes to improve the user experience when
+2.0 API. It allows clients that only support the legacy API to make some
-talking to a homeserver that is using the OAuth 2.0 API without actually having
+less-invasive changes to improve the user experience when talking to a
-to implement the full OAuth 2.0 API.
+homeserver that is using the OAuth 2.0 API without actually having to implement
+the full OAuth 2.0 API.
 
 ##### Client behaviour
 
@@ -1639,8 +1635,8 @@ For a client to be considered fully OAuth 2.0 aware it MUST:
 
 * Support the [`m.login.sso` authentication flow](#client-login-via-sso).
 * Where a `oauth_aware_preferred` value of `true` is present on an `m.login.sso`
-  flow then *only* offer that auth flow to the user.
+  flow, *only* offer that auth flow to the user.
-* Append `action=login` and `action=register` parameters to the [SSO redirect
+* Append `action=login` or `action=register` parameters to the [SSO redirect
   endpoints](#get_matrixclientv3loginssoredirect). The client might determine
   the value to use based on whether the user clicked a "Login" or "Register"
   button.

data/api/client-server/definitions/sso_login_flow.yaml

@@ -90,8 +90,9 @@ properties:
     type: boolean
     x-addedInMatrixVersion: "1.18"
     description: |
-      Whether the `m.login.sso` flow is preferred over other flows for
+      Whether the `m.login.sso` flow is preferred over other flows. If this is `true`,
-      [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients).
+      [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) MUST only
+      offer this flow to the user.
     example: true
 
 required: ['type']

data/api/client-server/registration.yaml

@@ -77,8 +77,9 @@ paths:
         {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
         MUST NOT use this endpoint when the server offers the [`m.login.sso`
         authentication flow](/client-server-api/#client-login-via-sso) with
-        `oauth_aware_preferred` set to `true`. Instead they MUST add the
+        `oauth_aware_preferred` set to `true`. Instead they MUST use the
-        `action=register` parameter to the SSO redirect endpoint.
+        [`/login/sso/redirect`](/client-server-api/#get_matrixclientv3loginssoredirect)
+        endpoint, adding the `action=register` parameter.
         {{% /boxes/warning %}}
       operationId: register
       parameters:

data/api/client-server/sso_login_redirect.yaml

@@ -41,8 +41,7 @@ paths:
           name: action
           x-addedInMatrixVersion: "1.18"
           description: |-
-            The action that the user wishes to take at the SSO redirect, for
+            The action that the user wishes to take at the SSO redirect.
-            [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients).
 
             The following values are supported:
               * `login`: the SSO redirect is for the purposes of signing an
@@ -96,8 +95,7 @@ paths:
           name: action
           x-addedInMatrixVersion: "1.18"
           description: |-
-            The action that the user wishes to take at the SSO redirect, for
+            The action that the user wishes to take at the SSO redirect.
-            [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients).
 
             The following values are supported:
               * `login`: the SSO redirect is for the purposes of signing an