Full stops, language.

api/server-server/definitions/edu.yaml

@@ -22,16 +22,16 @@ example:
 properties:
   edu_type:
     type: string
-    description: The type of ephemeral message
+    description: The type of ephemeral message.
-    example: "!abc123:matrix.org"
+    example: "m.presence"
   origin:
     type: string
-    description: The server name sending the ephemeral message
+    description: The server name sending the ephemeral message.
     example: "matrix.org"    
   destination:
     type: string
-    description: The server name receiving the ephemeral message
+    description: The server name receiving the ephemeral message.
     example: "elsewhere.com"
   content:
     type: object
-    description: The content of the ephemeral message
+    description: The content of the ephemeral message.

api/server-server/definitions/pdu.yaml

@@ -23,20 +23,20 @@ allOf:
       hashes:
         type: object
         title: Event Hash
-        description: Hashes of the PDU, following the algorithm specified in `Signing Events`_
+        description: Hashes of the PDU, following the algorithm specified in `Signing Events`_.
         example: {
           "sha256": "thishashcoversallfieldsincasethisisredacted"
         }
         properties:
           sha256:
             type: string
-            description: The hash
+            description: The hash.
-            example: thishashcoversallfieldsincasethisisredacted
+            example: thishashcoversallfieldsincasthisisredacted
         required: ['sha256']
       signatures:
         type: object
         description: |-
-          Signatures of the redacted PDU, following the algorithm specified in `Signing Events`_
+          Signatures of the redacted PDU, following the algorithm specified in `Signing Events`_.
         example: {
           "example.com": {
             "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"

api/server-server/definitions/transaction.yaml

@@ -20,16 +20,16 @@ properties:
   origin:
     type: string
     description: |-
-      The ``server_name`` of hoemserver sending this transaction
+      The ``server_name`` of the hoemserver sending this transaction.
     example: "example.org"
   origin_server_ts:
     type: integer
     format: int64
-    description: Timestamp in milliseconds on originating homeserver when this transaction started
+    description: Timestamp in milliseconds on originating homeserver when this transaction started.
     example: 1234567890
   pdus:
     type: array
-    description: List of persistent updates to rooms
+    description: List of persistent updates to rooms.
     items:
       $ref: "pdu.yaml"
 required: ['origin', 'origin_server_ts', 'pdus']

api/server-server/definitions/unsigned_pdu.yaml

@@ -19,15 +19,15 @@ example:
 properties:
   room_id:
     type: string
-    description: Room identifier
+    description: Room identifier.
     example: "!abc123:matrix.org"
   sender:
     type: string
-    description: The ID of the user sending the event
+    description: The ID of the user sending the event.
     example: "@someone:matrix.org"
   origin:
     type: string
-    description: The ``server_name`` of the homeserver that created this event
+    description: The ``server_name`` of the homeserver that created this event.
     example: "matrix.org"    
   origin_server_ts:
     type: integer
@@ -47,13 +47,13 @@ properties:
     example: "my_key"
   content:
     type: object
-    description: The content of the event
+    description: The content of the event.
     example: {"key": "value"}
   prev_events:
     type: array
     description: |-
       Event IDs and hashes of the most recent events in the room that the homeserver was aware
-      of when it made this event
+      of when it made this event.
     items:
       type: array
       maxItems: 2
@@ -70,16 +70,16 @@ properties:
           properties:
             sha256:
               type: string
-              description: The event hash
+              description: The event hash.
               example: abase64encodedsha256hashshouldbe43byteslong
           required: ['sha256']
   depth:
     type: integer
-    description: The maximum depth of the ``prev_events``, plus one
+    description: The maximum depth of the ``prev_events``, plus one.
     example: 12
   auth_events:
     type: array
-    description: Event IDs and hashes for the "auth events" of this event
+    description: Event IDs and hashes for the "auth events" of this event.
     items:
       type: array
       maxItems: 2
@@ -96,16 +96,16 @@ properties:
           properties:
             sha256:
               type: string
-              description: The event hash
+              description: The event hash.
               example: abase64encodedsha256hashshouldbe43byteslong
           required: ['sha256']
   redacts:
     type: string
-    description: For redaction events, the ID of the event being redacted
+    description: For redaction events, the ID of the event being redacted.
     example: "$def456:matrix.org"
   unsigned:
     type: object
-    description: Additional data added by the origin server but not covered by the ``signatures``
+    description: Additional data added by the origin server but not covered by the ``signatures``.
     example: {"key": "value"}
 required:
   - room_id

api/server-server/events.yaml

@@ -33,37 +33,37 @@ paths:
         - in: path
           name: roomId
           type: string
-          description: The room ID to get state for
+          description: The room ID to get state for.
           required: true
           x-example: "!abc123:matrix.org"
       responses:
         200:
-          description: The room state for the room (kept under ``pdus``)
+          description: The room state for the room (kept under ``pdus``).
           schema:
             $ref: "definitions/transaction.yaml"
   "/event/{eventId}":
     get:
       summary: Get a single event
       description: |-
-        Retrieves a single event
+        Retrieves a single event.
       operationId: getEvent
       parameters:
         - in: path
           name: eventId
           type: string
-          description: The event ID to get
+          description: The event ID to get.
           required: true
           x-example: "$abc123:matrix.org"
       responses:
         200:
-          description: A transaction containing a single PDU which is the event requested
+          description: A transaction containing a single PDU which is the event requested.
           schema:
             $ref: "definitions/transaction.yaml"
   "/backfill/{roomId}":
     get:
       summary: Retrieves the events which precede the given event
       description: |-
-        Retreives a sliding-window history of previous PDUs that occurred on the given room.
+        Retreives a sliding-window history of previous PDUs that occurred in the given room.
         Starting from the PDU ID(s) given in the ``v`` argument, the PDUs that preceded it
         are retrived, up to the total number given by the ``limit``.
       operationId: backfillRoom
@@ -71,19 +71,19 @@ paths:
         - in: path
           name: roomId
           type: string
-          description: The room ID to backfill
+          description: The room ID to backfill.
           required: true
           x-example: "!abc123:matrix.org"
         - in: query
           name: v
           type: string # TODO: The description says this is plural - figure out how to specify multiple, and spec it
-          description: The event ID to backfill from
+          description: The event ID to backfill from.
           required: true
           x-example: "$abc123:matrix.org"
         - in: query
           name: limit
           type: integer
-          description: The maximum number of events to retrieve
+          description: The maximum number of events to retrieve.
           required: true # TODO: Verify
           x-example: 10
       responses:
@@ -91,6 +91,7 @@ paths:
           description: A transaction containing the PDUs that preceded the given event(s).
           schema:
             $ref: "definitions/transaction.yaml"
+  # TODO: It's possible that this endpoint doesn't exist anymore - verify
   "/pull":
     get:
       summary: Stream events later than a given point in history
@@ -101,7 +102,7 @@ paths:
         - in: query
           name: v
           type: string # TODO: The description says this is plural - figure out how to specify multiple, and spec it
-          description: The event ID to backfill from
+          description: The event ID to backfill from.
           required: true
           x-example: "$abc123:matrix.org"
         - in: query