Merge pull request #1379 from turt2live/travis/preset-guests

Document guest_access in /createRoom presets; Make presets a table

api/client-server/create_room.yaml

@@ -1,4 +1,5 @@
 # Copyright 2016 OpenMarket Ltd
+# Copyright 2018 New Vector Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -40,7 +41,7 @@ paths:
         0. A default ``m.room.power_levels`` event, giving the room creator
            (and not other members) permission to send state events.
         
-        1. Events set by ``presets``.
+        1. Events set by the ``preset``.
 
         2. Events listed in ``initial_state``, in the order that they are
            listed.
@@ -49,6 +50,16 @@ paths:
 
         4. Invite events implied by ``invite`` and ``invite_3pid``.
 
+        The available presets do the following with respect to room state:
+
+        ========================  ==============  ======================  ================  =========
+                 Preset           ``join_rules``  ``history_visibility``  ``guest_access``  Other
+        ========================  ==============  ======================  ================  =========
+        ``private_chat``          ``invite``      ``shared``              ``can_join``      
+        ``trusted_private_chat``  ``invite``      ``shared``              ``can_join``      All invitees are given the same power level as the room creator.
+        ``public_chat``           ``public``      ``shared``              ``forbidden``     
+        ========================  ==============  ======================  ================  =========
+
       operationId: createRoom
       security:
         - accessToken: []
@@ -142,7 +153,7 @@ paths:
                   room. The expected format of the state events are an object
                   with type, state_key and content keys set.
 
-                  Takes precedence over events set by ``presets``, but gets
+                  Takes precedence over events set by ``preset``, but gets
                   overriden by ``name`` and ``topic`` keys.
                 items:
                   type: object
@@ -163,20 +174,7 @@ paths:
                 enum: ["private_chat", "public_chat", "trusted_private_chat"]
                 description: |-
                   Convenience parameter for setting various default state events
-                  based on a preset. Must be either:
-
-                  ``private_chat`` =>
-                    ``join_rules`` is set to ``invite``.
-                    ``history_visibility`` is set to ``shared``.
-
-                  ``trusted_private_chat`` =>
-                      ``join_rules`` is set to ``invite``.
-                      ``history_visibility`` is set to ``shared``.
-                      All invitees are given the same power level as the room creator.
-
-                  ``public_chat``: =>
-                      ``join_rules`` is set to ``public``.
-                      ``history_visibility`` is set to ``shared``.
+                  based on a preset.
               is_direct:
                 type: boolean
                 description: |-

changelogs/client_server.rst

@@ -45,6 +45,8 @@ Unreleased changes
     (`#1274 <https://github.com/matrix-org/matrix-doc/pull/1274>`_).
   - Document the GET version of ``/login``
     (`#1361 <https://github.com/matrix-org/matrix-doc/pull/1361>`_).
+  - Document guest access in ``/createRoom`` presets
+    (`#1379 <https://github.com/matrix-org/matrix-doc/pull/1379>`_).
   - Document the CORS/preflight headers
     (`#1365 <https://github.com/matrix-org/matrix-doc/pull/1365>`_).