From 6646146f8cdc94cdce7ed6bf18677330d688e7dd Mon Sep 17 00:00:00 2001
From: Patrick Cloke <clokep@users.noreply.github.com>
Date: Fri, 13 Jun 2025 10:26:20 -0400
Subject: [PATCH] Accept minor suggestions from code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 content/client-server-api/modules/guest_access.md |  2 +-
 data/api/client-server/capabilities.yaml          | 13 ++++++++-----
 data/api/client-server/profile.yaml               | 12 ++++++------
 3 files changed, 15 insertions(+), 12 deletions(-)

diff --git a/content/client-server-api/modules/guest_access.md b/content/client-server-api/modules/guest_access.md
index 7656beb3..0b61f8f4 100644
--- a/content/client-server-api/modules/guest_access.md
+++ b/content/client-server-api/modules/guest_access.md
@@ -63,7 +63,7 @@ for sending events:
 The following API endpoints are allowed to be accessed by guest accounts
 for their own account maintenance:
 
-* [PUT /profile/{userId}/{key_name}](#put_matrixclientv3profileuseridkeyname)
+* [PUT /profile/{userId}/{keyName}](#put_matrixclientv3profileuseridkeyname)
 * [GET /devices](#get_matrixclientv3devices)
 * [GET /devices/{deviceId}](#get_matrixclientv3devicesdeviceid)
 * [PUT /devices/{deviceId}](#put_matrixclientv3devicesdeviceid)
diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 4a0af7f4..4a9209ac 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -77,13 +77,13 @@ paths:
                         $ref: '#/components/schemas/booleanCapability'
                         description: |
                           **Deprecated:** Capability to indicate if the user can change their display name.
-                          Please refer to `m.profile_fields` for extended profile management.
+                          Refer to `m.profile_fields` for extended profile management.
                       m.set_avatar_url:
                         deprecated: true
                         $ref: '#/components/schemas/booleanCapability'
                         description: |
                           **Deprecated:** Capability to indicate if the user can change their avatar.
-                          Please refer to `m.profile_fields` for extended profile management.
+                          Refer to `m.profile_fields` for extended profile management.
                       m.3pid_changes:
                         $ref: '#/components/schemas/booleanCapability'
                         description: Capability to indicate if the user can change 3PID associations
@@ -96,8 +96,11 @@ paths:
                         x-addedInMatrixVersion: "1.14"
                         type: object
                         title: ProfileFieldsCapability
-                        description: Capability to indicate if the user can set or modify extended profile fields.
-                          If absent, clients should assume custom profile fields are supported.
+                        description: Capability to indicate if the user can set or modify extended profile fields via
+                            [`PUT /_matrix/client/v3/profile/{userId}/{keyName}`](/client-server-api/#put_matrixclientv3profileuseridkeyname).
+                          If absent, clients should assume custom profile fields are supported, provided the
+                          response from [`/versions`](/client-server-api/#get_matrixclientversions) indicates
+                          support for a sufficiently recent spec version.
                         properties:
                           allowed:
                             type: array
@@ -119,7 +122,7 @@ paths:
                               - "org.example.secret_field"
                           enabled:
                             type: boolean
-                            description: True if the user can set or modify any extended profile fields, false otherwise.
+                            description: `true` if the user can set or modify any extended profile fields, `false` otherwise.
                             example: true
                         required:
                           - enabled
diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index dfe4cb7b..b0feea82 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -23,8 +23,8 @@ paths:
       summary: Set a profile field for a user.
       description: |-
         Set or update a profile field for a user. Must be authenticated with an
-        access token authorised to make changes. Servers may impose size limits
-        on individual fields, and the total profile must be under 64 KiB.
+        access token authorised to make changes. Servers MAY impose size limits
+        on individual fields, and the total profile MUST be under 64 KiB.
 
         **Note**: Setting a field to `null` keeps the key but with a `null` value,
         which some servers may reject. To remove a field completely, use the
@@ -36,7 +36,7 @@ paths:
       parameters:
         - in: path
           name: userId
-          description: The user whose profile field to set.
+          description: The user whose profile field should be set.
           required: true
           example: "@alice:example.com"
           schema:
@@ -133,7 +133,7 @@ paths:
       parameters:
         - in: path
           name: userId
-          description: The user whose profile field to get.
+          description: The user whose profile field should be returned.
           required: true
           example: "@alice:example.com"
           schema:
@@ -196,14 +196,14 @@ paths:
       parameters:
         - in: path
           name: userId
-          description: The user whose profile field to delete.
+          description: The user whose profile field should be deleted.
           required: true
           example: "@alice:example.com"
           schema:
             type: string
         - in: path
           name: keyName
-          description: The profile field key name to delete. It must be either
+          description: The key name of the profile field to delete. It must be either
             `avatar_url`, `displayname`, or a custom field following the
             [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
           required: true