Tweaks/clarifications to search spec

Fixes https://matrix.org/jira/browse/SPEC-305

api/client-server/search.yaml

@@ -20,12 +20,19 @@ securityDefinitions:
 paths:
   "/search":
     post:
-      summary: Search server side for things.
+      summary: Perform a server-side search.
       description: |-
         Performs a full text search across different categories.
       security:
         - accessToken: []
       parameters:
+        - in: query
+          name: next_batch
+          type: string
+          description: |-
+            The point to return events from. If given, this should be a
+            `next_batch` result from a previous call to this endpoint.
+          x-example: "YWxsCgpOb25lLDM1ODcwOA"
         - in: body
           name: body
           schema:
@@ -260,8 +267,11 @@ paths:
                                 type: string
                                 title: Next Batch in Group
                                 description: |-
-                                  Token that can be used to get the next
-                                  batch of results in the group, if exists.
+                                  Token that can be used to get the next batch
+                                  of results in the group, by passing as the
+                                  `next_batch` parameter to the next call. If
+                                  this field is absent, there are no more
+                                  results in this group.
                               order:
                                 type: integer
                                 title: Group Order
@@ -280,7 +290,9 @@ paths:
                         title: Next Batch
                         description: |-
                           Token that can be used to get the next batch of
-                          results, if exists.
+                          results, by passing as the `next_batch` parameter to
+                          the next call. If this field is absent, there are no
+                          more results.
           examples:
             application/json: |-
                {

specification/modules/search.rst

@@ -8,8 +8,6 @@ rooms that the user has been in, including those that they have left. Only
 events that the user is allowed to see will be searched, e.g. it won't include
 events in rooms that happened after you left.
 
-Client behaviour
-----------------
 {{search_http_api}}
 
 Search Categories
@@ -36,9 +34,9 @@ The search will *not* include rooms that are end to end encrypted.
 The results include a ``rank`` key that can be used to sort the results by
 relevancy. The higher the ``rank`` the more relevant the result is.
 
-The value of ``count`` may not match the number of results. For example due to
-the search query matching 1000s of results and the server truncating the
-response.
+The value of ``count`` gives an approximation of the total number of
+results. Homeservers may give an estimate rather than an exact value for this
+field.
 
 Ordering
 --------
@@ -84,7 +82,7 @@ The currently supported locations for the ``next_batch`` token are:
 - ``search_categories.<category>.groups.<group_key>.<group_id>.next_batch``
 
 A server need not support pagination, even if there are more matching results.
-In which case they must not return a ``next_batch`` token in the response.
+In that case, they must not return a ``next_batch`` token in the response.
 
 
 Security considerations