Merge pull request #984 from matrix-org/rav/sync_timeout

Make clear that the /sync timeout is zero by default

api/client-server/sync.yaml

@@ -88,8 +88,12 @@ paths:
           name: timeout
           type: integer
           description: |-
-            The maximum time to poll in milliseconds before returning this
+            The maximum time to wait, in milliseconds, before returning this
-            request.
+            request. If no events (or other data) become available before this
+            time elapses, the server will return a response with empty fields.
+
+            By default, this is ``0``, so the server will return immediately
+            even if the response is empty.
           x-example: 30000
       responses:
         200:

specification/client_server_api.rst

@@ -949,11 +949,11 @@ You can visualise the range of events being returned as::
 
 Clients then receive new events by "long-polling" the homeserver via the
 ``/sync`` API, passing the value of the ``next_batch`` field from the response
-to the previous call as the ``since`` parameter. This involves specifying a
+to the previous call as the ``since`` parameter. The client should also pass a
-timeout in the request which will hold open the HTTP connection for a short
+``timeout`` parameter. The server will then hold open the HTTP connection for a
-period of time waiting for new events, returning early if an event occurs. Only
+short period of time waiting for new events, returning early if an event
-the ``/sync`` API (and the deprecated ``/events`` API) support long-polling in
+occurs. Only the ``/sync`` API (and the deprecated ``/events`` API) support
-this way.
+long-polling in this way.
 
 The response for such an incremental sync can be visualised as::