Clarify the homeserver's behaviour for user searching

The homeserver can implement its own algorithm, but is suggested to ensure the requesting user can reasonably see the other users.

The text is intentionally left vague for whether or not the API is local users only to give the homeserver some flexibility in this area.

General cleanup is also included in this commit.

Fixes https://github.com/matrix-org/matrix-doc/issues/1108

api/client-server/users.yaml

@@ -31,8 +31,13 @@ paths:
     post:
       summary: Searches the user directory.
       description: |-
-        This API performs a server-side search over all users registered on the server.
+        Performs a search for users on the homeserver. The homeserver may
-        It searches user ID and displayname case-insensitively for users that you share a room with or that are in public rooms.
+        determine which subset of users are searched, however the homeserver
+        is encouraged to only consider users the requesting user shares a
+        room with and those who reside in public rooms.
+
+        The search is performed case-insensitively on user IDs and display
+        names.
       operationId: searchUserDirectory
       security:
         - accessToken: []
@@ -48,7 +53,7 @@ paths:
                 example: "foo"
               limit:
                 type: number
-                description: The maximum number of results to return (Defaults to 10).
+                description: The maximum number of results to return. Defaults to 10.
                 example: 10
             required: ["search_term"]
       responses:
@@ -56,15 +61,15 @@ paths:
           description: The results of the search.
           examples:
             application/json: {
-                  "results": [
+              "results": [
-                    {
+                {
-                      "user_id": "@foo:bar.com",
+                  "user_id": "@foo:bar.com",
-                      "display_name": "Foo",
+                  "display_name": "Foo",
-                      "avatar_url": "mxc://bar.com/foo"
+                  "avatar_url": "mxc://bar.com/foo"
-                    }
+                }
-                  ],
+              ],
-                  "limited": false
+              "limited": false
-              }
+            }
           schema:
             type: object
             required: ["results", "limited"]