Format descriptions

Signed-off-by: Kai A. Hiller <git@kaialexhiller.de>

data/api/application-service/definitions/namespace_list.yaml

@@ -19,10 +19,13 @@ items:
   properties:
     regex:
       type: string
-      description: A POSIX regular expression defining which values this namespace includes.
+      description: >-
+        A POSIX regular expression defining which values this namespace includes.
     exclusive:
       type: boolean
-      description: A true or false value stating whether this application service has exclusive access to events within this namespace.
+      description: >-
+        A true or false value stating whether this application service has
+        exclusive access to events within this namespace.
   required:
     - regex
     - exclusive

data/api/application-service/definitions/protocol.yaml

@@ -16,7 +16,7 @@ allOf:
 - type: object
   properties:
     instances:
-      description: |-
+      description: >-
         A list of objects representing independent instances of configuration.
         For example, multiple networks on IRC if multiple are provided by the
         same application service.

data/api/application-service/definitions/protocol_base.yaml

@@ -15,7 +15,7 @@ title: Protocol
 type: object
 properties:
   user_fields:
-    description: |-
+    description: >-
       Fields which may be used to identify a third-party user. These should be
       ordered to suggest the way that entities may be grouped, where higher
       groupings are ordered first. For example, the name of a network should be
@@ -26,9 +26,9 @@ properties:
       description: Field used to identify a third-party user.
     example: ["network", "nickname"]
   location_fields:
-    description: |-
+    description: >-
-      Fields which may be used to identify a third-party location. These should be
+      Fields which may be used to identify a third-party location. These should
-      ordered to suggest the way that entities may be grouped, where higher
+      be ordered to suggest the way that entities may be grouped, where higher
       groupings are ordered first. For example, the name of a network should be
       searched before the name of a channel.
     type: array
@@ -41,10 +41,11 @@ properties:
     type: string
     example: "mxc://example.org/aBcDeFgH"
   field_types:
-    description: |-
+    description: >-
       The type definitions for the fields defined in `user_fields` and
-      `location_fields`. Each entry in those arrays MUST have an entry here.
+      `location_fields`. Each entry in those arrays MUST have an entry here. The
-      The `string` key for this object is the field name itself.
+      `string` key for this object is the field name itself.
+
 
       May be an empty object if no fields are defined.
     type: object
@@ -54,10 +55,11 @@ properties:
       type: object
       properties:
         regexp:
-          description: |-
+          description: >-
-            A regular expression for validation of a field's value. This may be relatively
+            A regular expression for validation of a field's value. This may be
-            coarse to verify the value as the application service providing this protocol
+            relatively coarse to verify the value as the application service
-            may apply additional validation or filtering.
+            providing this protocol may apply additional validation or
+            filtering.
           type: string
         placeholder:
           description: A placeholder serving as a valid example of the field value.

data/api/application-service/definitions/protocol_instance.yaml

@@ -20,9 +20,9 @@ properties:
     example: "Freenode"
   icon:
     type: string
-    description: |-
+    description: >-
-      An optional content URI representing the protocol. Overrides the one provided
+      An optional content URI representing the protocol. Overrides the one
-      at the higher level Protocol object.
+      provided at the higher level Protocol object.
     example: "mxc://example.org/JkLmNoPq"
   fields:
     type: object

data/api/application-service/definitions/registration.yaml

@@ -17,27 +17,37 @@ title: Registration
 properties:
   id:
     type: string
-    description: A unique, user-defined ID of the application service which will never change.
+    description: >-
+      A unique, user-defined ID of the application service which will never change.
   url:
     type: string
-    description: The URL for the application service. May include a path after the domain name. Optionally set to null if no traffic is required.
+    description: >-
+      The URL for the application service. May include a path after the domain
+      name. Optionally set to null if no traffic is required.
   as_token:
     type: string
-    description: A secret token that the application service will use to authenticate requests to the homeserver.
+    description: >-
+      A secret token that the application service will use to authenticate
+      requests to the homeserver.
   hs_token:
     type: string
-    description: A secret token that the homeserver will use authenticate requests to the application service.
+    description: >-
+      A secret token that the homeserver will use authenticate requests to the
+      application service.
   sender_localpart:
     type: string
-    description: |-
+    description: >-
-      The localpart of the user associated with the application service. Events will be sent to the AS if this user is the target of the event, or
+      The localpart of the user associated with the application service. Events
-      is a joined member of the room where the event occurred.
+      will be sent to the AS if this user is the target of the event, or is a
+      joined member of the room where the event occurred.
   receive_ephemeral:
     type: boolean
     x-addedInMatrixVersion: "1.13"
-    description: |-
+    description: >-
-      Whether the application service wants to [receive ephemeral data](/application-service-api/#pushing-ephemeral-data).
+      Whether the application service wants to [receive ephemeral
-      
+      data](/application-service-api/#pushing-ephemeral-data).
+
+
       Defaults to `false` if not present.
   namespaces:
     type: object
@@ -47,7 +57,7 @@ properties:
       users:
         allOf:
           - $ref: namespace_list.yaml
-          - description: |-
+          - description: >-
               A list of namespaces defining the user IDs that the application
               service is interested in, in addition to its `sender_localpart`.
               Events will be sent to the AS if a local user matching one of the
@@ -56,23 +66,26 @@ properties:
       rooms:
         allOf:
           - $ref: namespace_list.yaml
-          - description: |-
+          - description: >-
               A list of namespaces defining the room IDs that the application
               service is interested in. All events sent in a room with an ID
               which matches one of the namespaces will be sent to the AS.
       aliases:
         allOf:
           - $ref: namespace_list.yaml
-          - description: |-
+          - description: >-
-              A list of namespaces defining the room aliases that the application
+              A list of namespaces defining the room aliases that the
-              service is interested in. All events sent in a room with an alias
+              application service is interested in. All events sent in a room
-              which matches one of the namespaces will be sent to the AS.
+              with an alias which matches one of the namespaces will be sent to
+              the AS.
   rate_limited:
     type: boolean
-    description: Whether requests from masqueraded users are rate-limited. The sender is excluded.
+    description: >-
+      Whether requests from masqueraded users are rate-limited. The sender is excluded.
   protocols:
     type: array
-    description: The external protocols which the application service provides (e.g. IRC).
+    description: >-
+      The external protocols which the application service provides (e.g. IRC).
     items:
       type: string
 required:

data/api/application-service/definitions/security.yaml

@@ -15,4 +15,5 @@
 homeserverAccessToken:
   type: http
   scheme: bearer
-  description: The `Bearer` `hs_token` provided by the application service's registration.
+  description: >-
+    The `Bearer` `hs_token` provided by the application service's registration.

data/api/application-service/ping.yaml

@@ -20,13 +20,18 @@ paths:
     post:
       x-addedInMatrixVersion: "1.7"
       summary: Ping the application service
-      description: |-
+      description: >-
         This API is called by the homeserver to ensure that the connection works
         and the `hs_token` the homeserver has is correct.
 
+
         Currently this is only called by the homeserver as a direct result of
         the application service calling
-        [`POST /_matrix/client/v1/appservice/{appserviceId}/ping`](#post_matrixclientv1appserviceappserviceidping).
+        [`POST /_matrix/client/v1/appservice/{appserviceId}/ping`].
+
+
+        [`POST /_matrix/client/v1/appservice/{appserviceId}/ping`]:
+          <#post_matrixclientv1appserviceappserviceidping>
       operationId: ping
       security:
         - homeserverAccessToken: []
@@ -41,13 +46,14 @@ paths:
               properties:
                 transaction_id:
                   type: string
-                  description: |-
+                  description: >-
                     A transaction ID for the ping, copied directly from the
                     `POST /_matrix/client/v1/appservice/{appserviceId}/ping` call.
         description: Ping body with optional transaction ID.
       responses:
         "200":
-          description: The provided `hs_token` is valid and the ping request was successful.
+          description: >-
+            The provided `hs_token` is valid and the ping request was successful.
           content:
             application/json:
               schema:

data/api/application-service/protocols.yaml

@@ -20,10 +20,10 @@ paths:
     get:
       summary: Retrieve metadata about a specific protocol that the application
         service supports.
-      description: |-
+      description: >-
         This API is called by the homeserver when it wants to present clients
-        with specific information about the various third-party networks that
+        with specific information about the various third-party networks that an
-        an application service supports.
+        application service supports.
       operationId: getProtocolMetadata
       security:
         - homeserverAccessToken: []
@@ -43,9 +43,10 @@ paths:
               schema:
                 $ref: definitions/protocol.yaml
         "401":
-          description: |-
+          description: >-
-            The homeserver has not supplied credentials to the application service.
+            The homeserver has not supplied credentials to the application
-            Optional error information can be included in the body of this response.
+            service. Optional error information can be included in the body of
+            this response.
           content:
             application/json:
               schema:
@@ -80,10 +81,10 @@ paths:
   "/thirdparty/user/{protocol}":
     get:
       summary: Retrieve the Matrix User ID of a corresponding third-party user.
-      description: |-
+      description: >-
-        This API is called by the homeserver in order to retrieve a Matrix
+        This API is called by the homeserver in order to retrieve a Matrix User
-        User ID linked to a user on the third-party network, given a set of
+        ID linked to a user on the third-party network, given a set of user
-        user parameters.
+        parameters.
       operationId: queryUserByProtocol
       security:
         - homeserverAccessToken: []
@@ -97,9 +98,9 @@ paths:
             type: string
         - in: query
           name: fields
-          description: |-
+          description: >-
-            One or more custom fields that are passed to the application
+            One or more custom fields that are passed to the application service
-            service to help identify the user.
+            to help identify the user.
           schema:
             type: object
             additionalProperties:
@@ -112,9 +113,10 @@ paths:
               schema:
                 $ref: definitions/user_batch.yaml
         "401":
-          description: |-
+          description: >-
-            The homeserver has not supplied credentials to the application service.
+            The homeserver has not supplied credentials to the application
-            Optional error information can be included in the body of this response.
+            service. Optional error information can be included in the body of
+            this response.
           content:
             application/json:
               schema:
@@ -149,7 +151,8 @@ paths:
   "/thirdparty/location/{protocol}":
     get:
       summary: Retrieve Matrix-side portal rooms leading to a third-party location.
-      description: Retrieve a list of Matrix portal rooms that lead to the matched
+      description: >-
+        Retrieve a list of Matrix portal rooms that lead to the matched
         third-party location.
       operationId: queryLocationByProtocol
       security:
@@ -164,9 +167,9 @@ paths:
             type: string
         - in: query
           name: fields
-          description: |-
+          description: >-
-            One or more custom fields that are passed to the application
+            One or more custom fields that are passed to the application service
-            service to help identify the third-party location.
+            to help identify the third-party location.
           schema:
             type: object
             additionalProperties:
@@ -179,9 +182,10 @@ paths:
               schema:
                 $ref: definitions/location_batch.yaml
         "401":
-          description: |-
+          description: >-
-            The homeserver has not supplied credentials to the application service.
+            The homeserver has not supplied credentials to the application
-            Optional error information can be included in the body of this response.
+            service. Optional error information can be included in the body of
+            this response.
           content:
             application/json:
               schema:
@@ -216,9 +220,8 @@ paths:
   /thirdparty/location:
     get:
       summary: Reverse-lookup third-party locations given a Matrix room alias.
-      description: |-
+      description: >-
-        Retrieve an array of third-party network locations from a Matrix room
+        Retrieve an array of third-party network locations from a Matrix room alias.
-        alias.
       operationId: queryLocationByAlias
       security:
         - homeserverAccessToken: []
@@ -236,9 +239,10 @@ paths:
               schema:
                 $ref: definitions/location_batch.yaml
         "401":
-          description: |-
+          description: >-
-            The homeserver has not supplied credentials to the application service.
+            The homeserver has not supplied credentials to the application
-            Optional error information can be included in the body of this response.
+            service. Optional error information can be included in the body of
+            this response.
           content:
             application/json:
               schema:
@@ -291,9 +295,10 @@ paths:
               schema:
                 $ref: definitions/user_batch.yaml
         "401":
-          description: |-
+          description: >-
-            The homeserver has not supplied credentials to the application service.
+            The homeserver has not supplied credentials to the application
-            Optional error information can be included in the body of this response.
+            service. Optional error information can be included in the body of
+            this response.
           content:
             application/json:
               schema:

data/api/application-service/query_room.yaml

@@ -20,12 +20,12 @@ paths:
   "/rooms/{roomAlias}":
     get:
       summary: Query if a room alias should exist on the application service.
-      description: |-
+      description: >-
-        This endpoint is invoked by the homeserver on an application service to query
+        This endpoint is invoked by the homeserver on an application service to
-        the existence of a given room alias. The homeserver will only query room
+        query the existence of a given room alias. The homeserver will only
-        aliases inside the application service's `aliases` namespace. The
+        query room aliases inside the application service's `aliases` namespace.
-        homeserver will send this request when it receives a request to join a
+        The homeserver will send this request when it receives a request to join
-        room alias within the application service's namespace.
+        a room alias within the application service's namespace.
       operationId: queryRoomByAlias
       security:
         - homeserverAccessToken: []
@@ -39,7 +39,7 @@ paths:
             type: string
       responses:
         "200":
-          description: |-
+          description: >-
             The application service indicates that this room alias exists. The
             application service MUST have created a room and associated it with
             the queried room alias using the client-server API. Additional
@@ -53,9 +53,10 @@ paths:
                 response:
                   value: {}
         "401":
-          description: |-
+          description: >-
-            The homeserver has not supplied credentials to the application service.
+            The homeserver has not supplied credentials to the application
-            Optional error information can be included in the body of this response.
+            service. Optional error information can be included in the body of
+            this response.
           content:
             application/json:
               schema:
@@ -77,9 +78,10 @@ paths:
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
                   }
         "404":
-          description: |-
+          description: >-
-            The application service indicates that this room alias does not exist.
+            The application service indicates that this room alias does not
-            Optional error information can be included in the body of this response.
+            exist. Optional error information can be included in the body of
+            this response.
           content:
             application/json:
               schema:

data/api/application-service/query_user.yaml

@@ -20,12 +20,13 @@ paths:
   "/users/{userId}":
     get:
       summary: Query if a user should exist on the application service.
-      description: |-
+      description: >-
-        This endpoint is invoked by the homeserver on an application service to query
+        This endpoint is invoked by the homeserver on an application service to
-        the existence of a given user ID. The homeserver will only query user IDs
+        query the existence of a given user ID. The homeserver will only query
-        inside the application service's `users` namespace. The homeserver will
+        user IDs inside the application service's `users` namespace. The
-        send this request when it receives an event for an unknown user ID in
+        homeserver will send this request when it receives an event for an
-        the application service's namespace, such as a room invite.
+        unknown user ID in the application service's namespace, such as a room
+        invite.
       operationId: queryUserById
       security:
         - homeserverAccessToken: []
@@ -39,9 +40,9 @@ paths:
             type: string
       responses:
         "200":
-          description: |-
+          description: >-
-            The application service indicates that this user exists. The application
+            The application service indicates that this user exists. The
-            service MUST create the user using the client-server API.
+            application service MUST create the user using the client-server API.
           content:
             application/json:
               schema:
@@ -50,9 +51,10 @@ paths:
                 response:
                   value: {}
         "401":
-          description: |-
+          description: >-
-            The homeserver has not supplied credentials to the application service.
+            The homeserver has not supplied credentials to the application
-            Optional error information can be included in the body of this response.
+            service. Optional error information can be included in the body of
+            this response.
           content:
             application/json:
               schema:
@@ -74,9 +76,10 @@ paths:
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
                   }
         "404":
-          description: |-
+          description: >-
             The application service indicates that this user does not exist.
-            Optional error information can be included in the body of this response.
+            Optional error information can be included in the body of this
+            response.
           content:
             application/json:
               schema:

data/api/application-service/transactions.yaml

@@ -20,20 +20,21 @@ paths:
   "/transactions/{txnId}":
     put:
       summary: Send some events to the application service.
-      description: |-
+      description: >-
-        This API is called by the homeserver when it wants to push an event
+        This API is called by the homeserver when it wants to push an event (or
-        (or batch of events) to the application service.
+        batch of events) to the application service.
 
-        Note that the application service should distinguish state events
+
-        from message events via the presence of a `state_key`, rather than
+        Note that the application service should distinguish state events from
-        via the event type.
+        message events via the presence of a `state_key`, rather than via the
+        event type.
       operationId: sendTransaction
       security:
         - homeserverAccessToken: []
       parameters:
         - in: path
           name: txnId
-          description: |-
+          description: >-
             The transaction ID for this set of events. Homeservers generate
             these IDs and they are used to ensure idempotency of requests.
           required: true
@@ -73,15 +74,19 @@ paths:
                 ephemeral:
                   type: array
                   x-addedInMatrixVersion: "1.13"
-                  description: |-
+                  description: >-
-                    A list of ephemeral data, if the `receive_ephemeral` setting was enabled in the
+                    A list of ephemeral data, if the `receive_ephemeral` setting
+                    was enabled in the
                     [registration](/application-service-api/#registration) file.
 
-                    There are only three event types that can currently occur in this list: `m.presence`,
+
-                    `m.typing`, and `m.receipt`. Room-scoped ephemeral data (`m.typing` and
+                    There are only three event types that can currently occur in
-                    `m.receipt`) MUST include a `room_id` property to identify the room that they
+                    this list: `m.presence`, `m.typing`, and `m.receipt`.
+                    Room-scoped ephemeral data (`m.typing` and `m.receipt`) MUST
+                    include a `room_id` property to identify the room that they
                     were sent in.
 
+
                     This property can be omitted if it would be empty.
                   items:
                     $ref: ../../event-schemas/schema/core-event-schema/event.yaml