Merge remote-tracking branch 'matrix-org/master' into travis/better-errors

api/client-server/banning.yaml

@@ -61,7 +61,8 @@ paths:
                 description: The fully qualified user ID of the user being banned.
               reason:
                 type: string
-                description: The reason the user has been banned.
+                description: The reason the user has been banned. This will be supplied as the 
+                  ``reason`` on the target's updated `m.room.member`_ event.
             required: ["user_id"]
       responses:
         200:

api/client-server/content-repo.yaml

@@ -299,3 +299,44 @@ paths:
             "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Media
+  "/config":
+    get:
+      summary: Get the configuration for the content repository.
+      description: |-
+        This endpoint allows clients to retrieve the configuration of the content
+        repository, such as upload limitations.
+        Clients SHOULD use this as a guide when using content repository endpoints.
+        All values are intentionally left optional. Clients SHOULD follow
+        the advice given in the field description when the field is not available.
+
+        **NOTE:** Both clients and server administrators should be aware that proxies
+        between the client and the server may affect the apparent behaviour of content
+        repository APIs, for example, proxies may enforce a lower upload size limit
+        than is advertised by the server on this endpoint.
+      operationId: getConfig
+      produces: ["application/json"]
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: The public content repository configuration for the matrix server.
+          schema:
+            type: object
+            properties:
+              m.upload.size:
+                type: number
+                description: |- 
+                  The maximum size an upload can be in bytes.
+                  Clients SHOULD use this as a guide when uploading content.
+                  If not listed or null, the size limit should be treated as unknown.
+          examples:
+            application/json: {
+               "m.upload.size": 50000000
+            }
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+
+      tags:
+        - Media

api/client-server/joining.yaml

@@ -145,6 +145,15 @@ paths:
           description: The room identifier or alias to join.
           required: true
           x-example: "#monkeys:matrix.org"
+        - in: query
+          type: array
+          items:
+            type: string
+          name: server_name
+          description: |-
+            The servers to attempt to join the room through. One of the servers
+            must be participating in the room.
+          x-example: ["matrix.org", "elsewhere.ca"]
         - in: body
           name: third_party_signed
           schema:

api/client-server/kicking.yaml

@@ -34,6 +34,10 @@ paths:
         Kick a user from the room.
 
         The caller must have the required power level in order to perform this operation.
+        
+        Kicking a user adjusts the target member's membership state to be ``leave`` with an
+        optional ``reason``. Like with other membership changes, a user can directly adjust
+        the target member's state by making a request to ``/rooms/<room id>/state/m.room.member/<user id>``.
       operationId: kick
       security:
         - accessToken: []
@@ -59,7 +63,9 @@ paths:
                 description: The fully qualified user ID of the user being kicked.
               reason:
                 type: string
-                description: The reason the user has been kicked.
+                description: |-
+                  The reason the user has been kicked. This will be supplied as the 
+                  ``reason`` on the target's updated `m.room.member`_ event.
             required: ["user_id"]
       responses:
         200:

changelogs/client_server.rst

@@ -15,6 +15,8 @@ Unreleased changes
   - Sticker messages:
     - Add sticker message event definition.
     (`#1158 <https://github.com/matrix-org/matrix-doc/pull/1158>`_).
+  - Document the ``server_name`` parameter on ``/join/{roomIdOrAlias}``
+    (`#1364 <https://github.com/matrix-org/matrix-doc/pull/1364>`_).
   - Add 'token' parameter to /keys/query endpoint
     (`#1104 <https://github.com/matrix-org/matrix-doc/pull/1104>`_).
   - Add the room visibility options for the room directory
@@ -59,6 +61,8 @@ Unreleased changes
     (`#1380 <https://github.com/matrix-org/matrix-doc/pull/1380>`_).
   - Describe ``StateEvent`` for ``/createRoom``
     (`#1329 <https://github.com/matrix-org/matrix-doc/pull/1329>`_).
+  - Describe how the ``reason`` is handled for kicks/bans
+    (`#1362 <https://github.com/matrix-org/matrix-doc/pull/1362>`_).
   - Clarify that clients must leave rooms before forgetting them
     (`#1378 <https://github.com/matrix-org/matrix-doc/pull/1378>`_).
   - Clarify the request and result types on ``/search``

scripts/templating/matrix_templates/units.py

@@ -502,6 +502,11 @@ class MatrixUnits(Units):
                 # assign value expected for this param
                 val_type = param.get("type")  # integer/string
 
+                if val_type == "array":
+                    items = param.get("items")
+                    if items:
+                        val_type = "[%s]" % items.get("type")
+
                 if param.get("enum"):
                     val_type = "enum"
                     desc += (