Merge pull request #1569 from turt2live/travis/c2s/user-directory

Clarify the homeserver's behaviour for user searching

api/client-server/users.yaml

@@ -31,8 +31,16 @@ 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
+        MUST at a minimum consider the users the requesting user shares a
+        room with and those who reside in public rooms (known to the homeserver).
+        The search MUST consider local users to the homeserver, and SHOULD
+        query remote users as part of the search.
+
+        The search is performed case-insensitively on user IDs and display
+        names preferably using a collation determined based upon the 
+        ``Accept-Language`` header provided in the request, if present.
       operationId: searchUserDirectory
       security:
         - accessToken: []
@@ -48,7 +56,7 @@ paths:
                 example: "foo"
               limit:
                 type: integer
-                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:

changelogs/client_server/newsfragments/1569.clarification

@@ -0,0 +1 @@
+Clarify the homeserver's behaviour for searching users.