Add general clarity to the /createRoom endpoint

This commit does a number of things:
* Minor formatting/alignment changes
* Document the room_alias response key. This could be deprecated now, or forfeited, if needed.
* Remove the guest_can_join parameter - it is not actually supported
* Document the previously undocumented power_level_content_override parameter
* Clarify that the room_id is required on the response
* More clearly spell out which events are created as part of the request
* Clarify how the room alias becomes the canonical alias
* Clarify how the `visibility` may be used to determine a default preset to apply
* Document the `m.federate` creation content parameter, adding an option for the homeserver to define a default value

References:
* Preset being inferred by the visibility: cd32c19a60/synapse/handlers/room.py (L172-L177)
* Power level content overrides:
  * https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L198
  * https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L335-L359
* Aliases becoming canonical: https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L366-L370
* `m.federate` landing in the create event: https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L311-L315

Fixes https://github.com/matrix-org/matrix-doc/issues/1243
Fixes https://github.com/matrix-org/matrix-doc/issues/1471
Inspired by https://github.com/matrix-org/matrix-doc/issues/1213

api/client-server/create_room.yaml

@@ -39,16 +39,20 @@ paths:
         apply the events implied by the request in the following order:
 
         0. A default ``m.room.power_levels`` event, giving the room creator
-           (and not other members) permission to send state events.
+           (and not other members) permission to send state events. Overridden
+           by the ``power_level_content_override`` parameter.
         
-        1. Events set by the ``preset``.
+        1. Events set by the ``preset``. Currently these are the ``m.room.join_rules``,
+           ``m.room.history_visibility``, and ``m.room.guest_access`` state events.
 
         2. Events listed in ``initial_state``, in the order that they are
            listed.
 
-        3. Events implied by ``name`` and ``topic``.
+        3. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic``
+           state events).
 
-        4. Invite events implied by ``invite`` and ``invite_3pid``.
+        4. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with
+           ``membership: invite`` and ``m.room.third_party_invite``).
 
         The available presets do the following with respect to room state:
 
@@ -60,6 +64,9 @@ paths:
         ``public_chat``           ``public``      ``shared``              ``forbidden``     
         ========================  ==============  ======================  ================  =========
 
+        The server will create a ``m.room.create`` event in the room with the
+        requesting user as the creator, alongside other keys provided in the 
+        ``creation_content``.
       operationId: createRoom
       security:
         - accessToken: []
@@ -70,14 +77,14 @@ paths:
           schema:
             type: object
             example: {
-                "preset": "public_chat",
+              "preset": "public_chat",
-                "room_alias_name": "thepub",
+              "room_alias_name": "thepub",
-                "name": "The Grand Duke Pub",
+              "name": "The Grand Duke Pub",
-                "topic": "All about happy hour",
+              "topic": "All about happy hour",
-                "creation_content": {
+              "creation_content": {
-                    "m.federate": false
+                  "m.federate": false
-                }
               }
+            }
             properties:
               visibility:
                 type: string
@@ -89,6 +96,11 @@ paths:
                   ``private`` visibility if this key is not included. NB: This
                   should not be confused with ``join_rules`` which also uses the
                   word ``public``.
+
+                  If no ``preset`` is specificed, the server may use the visbility
+                  to determine which preset to use. A visbility of ``public``
+                  equates to a preset of ``public_chat`` and ``private`` visibility
+                  equates to a preset of ``private_chat``.
               room_alias_name:
                 type: string
                 description: |-
@@ -98,6 +110,9 @@ paths:
                   created the room. For example, if this was set to "foo" and
                   sent to the homeserver "example.com" the complete room alias
                   would be ``#foo:example.com``.
+
+                  The complete room alias will become the canonical alias for
+                  the room.
               name:
                 type: string
                 description: |-
@@ -145,6 +160,14 @@ paths:
                   The server will clobber the following keys: ``creator``. Future
                   versions of the specification may allow the server to clobber
                   other keys.
+                properties:
+                  "m.federate":
+                    type: boolean
+                    description: |-
+                      Whether users on other servers can join this room. Defaults
+                      to ``true`` or what the server specifies. Setting this to 
+                      ``false`` may prevent users from being invited as part of
+                      this room creation request if they reside on other servers.
               initial_state:
                 type: array
                 description: |-
@@ -181,10 +204,14 @@ paths:
                   This flag makes the server set the ``is_direct`` flag on the
                   ``m.room.member`` events sent to the users in ``invite`` and
                   ``invite_3pid``. See `Direct Messaging`_ for more information.
-              guest_can_join:
+              power_level_content_override:
-                type: boolean
+                title: Power Level Event Content
                 description: |-
-                  Allows guests to join the room. See `Guest Access`_ for more information.
+                  The power level content to override in the default power level
+                  event. This object is applied on top of the generated power
+                  level event prior to it being sent to the room. Defaults
+                  to overriding nothing.
+                $ref: "definitions/event-schemas/power_level_content_schema.yaml"
       responses:
         200:
           description: Information about the newly created room.
@@ -196,10 +223,17 @@ paths:
                 type: string
                 description: |-
                   The created room's ID.
+              room_alias:
+                type: string
+                description: |-
+                  The complete room alias for the room, if a room alias was created
+                  for the room.
+            required: ['room_id']
           examples:
             application/json: {
-                "room_id": "!sefiuhWgwghwWgh:example.com"
+              "room_id": "!sefiuhWgwghwWgh:example.com",
-              }
+              "room_alias": "#thepub:example.com"
+            }
         400:
           description: |-
 
@@ -218,6 +252,5 @@ paths:
               ``M_INVALID_ROOM_STATE``).
           schema:
             "$ref": "definitions/errors/error.yaml"
-
       tags:
         - Room creation

event-schemas/power_level_content_schema.yaml

@@ -0,0 +1,56 @@
+# 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.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+properties:
+  ban:
+    description: The level required to ban a user. Defaults to 50 if unspecified.
+    type: number
+  events:
+    additionalProperties:
+      type: number
+    description: The level required to send specific event types. This is a mapping from event type to power level required.
+    title: Event power levels
+    type: object
+  events_default:
+    description: |-
+        The default level required to send message events. Can be
+        overridden by the ``events`` key.  Defaults to 0 if unspecified.
+    type: number
+  invite:
+    description: The level required to invite a user. Defaults to 50 if unspecified.
+    type: number
+  kick:
+    description: The level required to kick a user. Defaults to 50 if unspecified.
+    type: number
+  redact:
+    description: The level required to redact an event. Defaults to 50 if unspecified.
+    type: number
+  state_default:
+    description: |-
+        The default level required to send state events. Can be overridden
+        by the ``events`` key. Defaults to 50 if unspecified, but 0 if
+        there is no ``m.room.power_levels`` event at all.
+    type: number
+  users:
+    additionalProperties:
+      type: number
+    description: The power levels for specific users. This is a mapping from ``user_id`` to power level for that user.
+    title: User power levels
+    type: object
+  users_default:
+    description: |-
+        The default power level for every user in the room, unless their
+        ``user_id`` is mentioned in the ``users`` key. Defaults to 0 if
+        unspecified.
+    type: number
+type: object

event-schemas/schema/m.room.power_levels

@@ -43,49 +43,7 @@ description: |-
 
 properties:
   content:
-    properties:
+    $ref: "../power_level_content_schema.yaml"
-      ban:
-        description: The level required to ban a user. Defaults to 50 if unspecified.
-        type: number
-      events:
-        additionalProperties:
-          type: number
-        description: The level required to send specific event types. This is a mapping from event type to power level required.
-        title: Event power levels
-        type: object
-      events_default:
-        description: |-
-            The default level required to send message events. Can be
-            overridden by the ``events`` key.  Defaults to 0 if unspecified.
-        type: number
-      invite:
-        description: The level required to invite a user. Defaults to 50 if unspecified.
-        type: number
-      kick:
-        description: The level required to kick a user. Defaults to 50 if unspecified.
-        type: number
-      redact:
-        description: The level required to redact an event. Defaults to 50 if unspecified.
-        type: number
-      state_default:
-        description: |-
-            The default level required to send state events. Can be overridden
-            by the ``events`` key. Defaults to 50 if unspecified, but 0 if
-            there is no ``m.room.power_levels`` event at all.
-        type: number
-      users:
-        additionalProperties:
-          type: number
-        description: The power levels for specific users. This is a mapping from ``user_id`` to power level for that user.
-        title: User power levels
-        type: object
-      users_default:
-        description: |-
-            The default power level for every user in the room, unless their
-            ``user_id`` is mentioned in the ``users`` key. Defaults to 0 if
-            unspecified.
-        type: number
-    type: object
   state_key:
     description: A zero-length string.
     pattern: '^$'