Add information about the initialSync API.

Outline and describe the keys from the initial sync API. Hide room-scoped
initial sync API for now as it is not implemented and needs more thought before
it can be specced.

1 files changed, 46 insertions, 8 deletions

diff --git a/docs/specification.rst b/docs/specification.rst
index eff9dcd03d..edd8f5dbfb 100644
--- a/docs/specification.rst
+++ b/docs/specification.rst
@@ -1089,21 +1089,59 @@ When a client logs in, they may have a list of rooms which they have already
 joined. These rooms may also have a list of events associated with them. The
 purpose of 'syncing' is to present the current room and event information in a
 convenient, compact manner. The events returned are not limited to room events;
-presence events will also be returned. There are two APIs provided:
+presence events will also be returned. A single syncing API is provided:
 
  - |initialSync|_ : A global sync which will present room and event information
    for all rooms the user has joined.
 
+.. TODO-spec room-scoped initial sync
  - |/rooms/<room_id>/initialSync|_ : A sync scoped to a single room. Presents
    room and event information for this room only.
+ - Room-scoped initial sync is Very Tricky because typically people would
+   want to sync the room then listen for any new content from that point
+   onwards. The event stream cannot do this for a single room currently.
+   As a result, commenting room-scoped initial sync at this time.
 
-.. TODO-doc kegan
-  - TODO: JSON response format for both types
-  - TODO: when would you use global? when would you use scoped?
-  - Room-scoped initial sync is Very Tricky because typically people would
-    want to sync the room then listen for any new content from that point
-    onwards. The event stream cannot do this for a single room currently.
-    Not sure if room-scoped initial sync should be included at this time.
+The |initialSync|_ API contains the following keys:
+
+``presence``
+  Description:
+    Contains a list of presence information for users the client is interested
+    in.
+  Format:
+    A JSON array of ``m.presence`` events.
+
+``end``
+  Description:
+    Contains an event stream token which can be used with the `Event Stream`_.
+  Format:
+    A string containing the event stream token.
+
+``rooms``
+  Description:
+    Contains a list of room information for all rooms the client has joined,
+    and limited room information on rooms the client has been invited to.
+  Format:
+    A JSON array containing Room Information JSON objects.
+
+Room Information:
+  Description:
+    Contains all state events for the room, along with a limited amount of
+    the most recent non-state events, configured via the ``limit`` query
+    parameter. Also contains additional keys with room metadata, such as the
+    ``room_id`` and the client's ``membership`` to the room.
+  Format:
+    A JSON object with the following keys:
+      ``room_id``
+        A string containing the ID of the room being described.
+      ``membership``
+        A string representing the client's membership status in this room.
+      ``messages``
+        An event stream JSON object containing a ``chunk`` of recent non-state
+        events, along with an ``end`` token. *NB: The name of this key will be
+        changed in a later version.*
+      ``state``
+        A JSON array containing all the current state events for this room.
 
 Getting events for a room
 -------------------------