Explicitly declare that the kick/ban reason will be on the membership…

… event Fixes matrix-org#798
turt2live · Jul 3, 2018 · 7d94aaa · 7d94aaa
1 parent 26a62bc
commit 7d94aaa
Show file tree

Hide file tree

Showing 2 changed files with 9 additions and 2 deletions.
diff --git a/api/client-server/banning.yaml b/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:

diff --git a/api/client-server/kicking.yaml b/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: