api/: More cleanup in descriptions

(and a fix in one example).

api/application-service/transactions.yaml

@@ -50,7 +50,7 @@ paths:
           x-example: "35"
         - in: body
           name: body
-          description: A list of events.
+          description: Transaction information
           schema:
             type: object
             example: {
@@ -59,7 +59,6 @@ paths:
                 {"$ref": "../../event-schemas/examples/m.room.message$m.text"}
               ]
             }
-            description: Transaction information
             properties:
               events:
                 type: array

api/client-server/device_management.yaml

@@ -121,7 +121,7 @@ paths:
                 description: |-
                   The new display name for this device. If not given, the
                   display name is unchanged.
-                example: My other phone
+            example: { "display_name": "My other phone" }
       responses:
         200:
           description: The device was successfully updated.

api/client-server/kicking.yaml

@@ -77,7 +77,8 @@ paths:
             type: object
         403:
           description: |-
-            You do not have permission to kick the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
+            You do not have permission to kick the user from the room. A meaningful ``errcode`` and
+            description error text will be returned. Example reasons for rejections are:
 
             - The kicker is not currently in the room.
             - The kickee is not currently in the room.

api/client-server/presence.yaml

@@ -62,7 +62,7 @@ paths:
                 description: The new presence state.
               status_msg:
                 type: string
-                description: "The status message to attach to this state."
+                description: The status message to attach to this state.
             required: ["presence"]
       responses:
         200:

api/client-server/profile.yaml

@@ -45,7 +45,7 @@ paths:
           x-example: "@alice:example.com"
         - in: body
           name: displayName
-          description: The display name info.
+          description: The new display name information.
           required: true
           schema:
             type: object
@@ -119,7 +119,7 @@ paths:
           x-example: "@alice:example.com"
         - in: body
           name: avatar_url
-          description: The avatar url info.
+          description: The new avatar information.
           required: true
           schema:
             type: object

api/client-server/room_upgrades.yaml

@@ -45,7 +45,6 @@ paths:
         - in: body
           name: body
           required: true
-          description: The request body
           schema:
             type: object
             properties:

api/server-server/public_rooms.yaml

@@ -86,7 +86,7 @@ paths:
           name: body
           required: true
           description: |-
-            Options for which rooms to return.
+            Options for which rooms to return, or empty object to use defaults.
           schema:
             type: object
             properties: