Annotate all the 'TODO' marks as relating to either the specification itself or the documentation thereof

1 files changed, 54 insertions, 50 deletions

diff --git a/docs/specification.rst b/docs/specification.rst
index 07c57f9dda..6dcdea3060 100644
--- a/docs/specification.rst
+++ b/docs/specification.rst
@@ -118,7 +118,7 @@ the account and looks like::
 The ``localpart`` of a user ID may be a user name, or an opaque ID identifying
 this user. They are case-insensitive.
 
-.. TODO
+.. TODO-spec
     - Need to specify precise grammar for Matrix IDs
 
 A "Home Server" is a server which provides C-S APIs and has the ability to
@@ -366,7 +366,7 @@ events which are visible to the client will appear in the event stream. When
 the request returns, an ``end`` token is included in the response. This token
 can be used in the next request to continue where the client left off.
 
-.. TODO
+.. TODO-spec
   How do we filter the event stream?
   Do we ever return multiple events in a single request?  Don't we get lots of request
   setup RTT latency if we only do one event per request? Do we ever support streaming
@@ -704,7 +704,7 @@ Rooms
 Creation
 --------
 .. TODO kegan
-  - TODO: Key for invite these users?
+  - TODO-spec: Key for invite these users?
   
 To create a room, a client has to use the |createRoom|_ API. There are various
 options which can be set when creating a room:
@@ -799,7 +799,7 @@ Modifying aliases
 .. NOTE::
   This section is a work in progress.
 
-.. TODO kegan
+.. TODO-doc kegan
     - path to edit aliases 
     - PUT /directory/room/<room alias>  { room_id : foo }
     - GET /directory/room/<room alias> { room_id : foo, servers: [a.com, b.com] }
@@ -811,11 +811,11 @@ Permissions
 .. NOTE::
   This section is a work in progress.
 
-.. TODO kegan
-    - TODO: What is a power level? How do they work? Defaults / required levels for X. How do they change
+.. TODO-doc kegan
+    - What is a power level? How do they work? Defaults / required levels for X. How do they change
       as people join and leave rooms? What do you do if you get a clash? Examples.
-    - TODO: List all actions which use power levels (sending msgs, inviting users, banning people, etc...)
-    - TODO: Room config - what is the event and what are the keys/values and explanations for them.
+    - List all actions which use power levels (sending msgs, inviting users, banning people, etc...)
+    - Room config - what is the event and what are the keys/values and explanations for them.
       Link through to respective sections where necessary. How does this tie in with permissions, e.g.
       give example of creating a read-only room.
 
@@ -845,7 +845,7 @@ defined in the following state events:
 
 Joining rooms
 -------------
-.. TODO kegan
+.. TODO-doc kegan
   - TODO: What does the home server have to do to join a user to a room?
 
 Users need to join a room in order to send and receive events in that room. A
@@ -883,7 +883,7 @@ received an invite.
 
 Inviting users
 --------------
-.. TODO kegan
+.. TODO-doc kegan
   - Can invite users to a room if the room config key TODO is set to TODO. Must have required power level.
   - Outline invite join dance. What is it? Why is it required? How does it work?
   - What does the home server have to do?
@@ -921,7 +921,7 @@ See the `Room events`_ section for more information on ``m.room.member``.
 
 Leaving rooms
 -------------
-.. TODO kegan
+.. TODO-spec kegan
   - TODO: Grace period before deletion?
   - TODO: Under what conditions should a room NOT be purged?
 
@@ -1076,7 +1076,7 @@ presence events will also be returned. There are two APIs provided:
  - |/rooms/<room_id>/initialSync|_ : A sync scoped to a single room. Presents
    room and event information for this room only.
 
-.. TODO kegan
+.. TODO-doc kegan
   - TODO: JSON response format for both types
   - TODO: when would you use global? when would you use scoped?
 
@@ -1098,7 +1098,7 @@ There are several APIs provided to ``GET`` events for a room:
   Response format:
     ``[ { state event }, { state event }, ... ]``
   Example:
-    TODO
+    TODO-doc
 
 
 |/rooms/<room_id>/members|_
@@ -1107,7 +1107,7 @@ There are several APIs provided to ``GET`` events for a room:
   Response format:
     ``{ "start": "<token>", "end": "<token>", "chunk": [ { m.room.member event }, ... ] }``
   Example:
-    TODO
+    TODO-doc
 
 |/rooms/<room_id>/messages|_
   Description:
@@ -1117,16 +1117,16 @@ There are several APIs provided to ``GET`` events for a room:
   Response format:
     ``{ "start": "<token>", "end": "<token>" }``
   Example:
-    TODO
+    TODO-doc
     
 |/rooms/<room_id>/initialSync|_
   Description:
     Get all relevant events for a room. This includes state events, paginated
     non-state events and presence events.
   Response format:
-    `` { TODO } ``
+    `` { TODO-doc } ``
   Example:
-    TODO
+    TODO-doc
 
 Redactions
 ----------
@@ -1153,7 +1153,7 @@ Room Events
 .. NOTE::
   This section is a work in progress.
 
-.. TODO dave?
+.. TODO-doc dave?
   - voip events?
 
 This specification outlines several standard event types, all of which are
@@ -1232,7 +1232,7 @@ prefixed with ``m.``
   Example:
     ``{ "join_rule": "public" }``
   Description:
-    TODO : Use docs/models/rooms.rst
+    TODO-doc : Use docs/models/rooms.rst
    
 ``m.room.power_levels``
   Summary:
@@ -1480,8 +1480,9 @@ the following:
   - ``offline`` : The user is not connected to an event stream.
   - ``free_for_chat`` : The user is generally willing to receive messages
     moreso than default.
-  - ``hidden`` : TODO. Behaves as offline, but allows the user to see the
-    client state anyway and generally interact with client features.
+  - ``hidden`` : Behaves as offline, but allows the user to see the client
+    state anyway and generally interact with client features. (Not yet
+    implemented in synapse).
 
 This basic ``presence`` field applies to the user as a whole, regardless of how
 many client devices they have connected. The home server should synchronise
@@ -1509,7 +1510,7 @@ Transmission
 .. NOTE::
   This section is a work in progress.
 
-.. TODO:
+.. TODO-doc:
   - Transmitted as an EDU.
   - Presence lists determine who to send to.
 
@@ -1534,17 +1535,23 @@ user, either:
 In the latter case, this allows for clients to display some minimal sense of
 presence information in a user list for a room.
 
+
 Typing notifications
 ====================
 .. NOTE::
   This section is a work in progress.
 
-.. TODO Leo
+.. TODO-doc Leo
     - what is the event type. Are they bundled with other event types? If so, which.
     - what are the valid keys / values. What do they represent. Any gotchas?
     - Timeouts. How do they work, who sets them and how do they expire. Does one
       have priority over another? Give examples.
 
+.. TODO-spec Leo
+    - actually define the client-server API; the only thing that currently
+      exists is entirely server-server
+
+
 Voice over IP
 =============
 Matrix can also be used to set up VoIP calls. This is part of the core
@@ -1681,12 +1688,13 @@ a call and the other party had accepted. Thusly, any media stream that had been
 setup for use on a call should be transferred and used for the call that
 replaces it.
  
+
 Profiles
 ========
 .. NOTE::
   This section is a work in progress.
 
-.. TODO
+.. TODO-doc
   - Metadata extensibility
   - Changing profile info generates m.presence events ("presencelike")
   - keys on m.presence are optional, except presence which is required
@@ -1712,9 +1720,10 @@ Identity
 .. NOTE::
   This section is a work in progress.
 
-.. TODO Dave
+.. TODO-doc Dave
   - 3PIDs and identity server, functions
 
+
 Federation
 ==========
 
@@ -1884,10 +1893,9 @@ All PDUs have:
     The maximum depth of the previous PDUs plus one.
 
 
-.. TODO paul
-  [[TODO(paul): Update this structure so that 'pdu_id' is a two-element
-  [origin,ref] pair like the prev_pdus are]]
-  
+.. TODO-spec paul
+  - Update this structure so that 'pdu_id' is a two-element [origin,ref] pair
+    like the prev_pdus are
 
 For state updates:
 
@@ -1967,18 +1975,10 @@ keys exist to support this:
 
  {...,
   "is_state":true,
-  "state_key":TODO
-  "power_level":TODO
-  "prev_state_id":TODO
-  "prev_state_origin":TODO}
-
-.. TODO paul
-  [[TODO(paul): At this point we should probably have a long description of how
-  State management works, with descriptions of clobbering rules, power levels, etc
-  etc... But some of that detail is rather up-in-the-air, on the whiteboard, and
-  so on. This part needs refining. And writing in its own document as the details
-  relate to the server/system as a whole, not specifically to server-server
-  federation.]]
+  "state_key":TODO-doc
+  "power_level":TODO-doc
+  "prev_state_id":TODO-doc
+  "prev_state_origin":TODO-doc}
 
 EDUs, by comparison to PDUs, do not have an ID, a context, or a list of
 "previous" IDs. The only mandatory fields for these are the type, origin and
@@ -2005,7 +2005,7 @@ For active pushing of messages representing live activity "as it happens"::
 
   PUT .../send/:transaction_id/
     Body: JSON encoding of a single Transaction
-    Response: TODO
+    Response: TODO-doc
 
 The transaction_id path argument will override any ID given in the JSON body.
 The destination name will be set to that of the receiving server itself. Each
@@ -2068,7 +2068,7 @@ Backfilling
 .. NOTE::
   This section is a work in progress.
 
-.. TODO
+.. TODO-doc
   - What it is, when is it used, how is it done
 
 SRV Records
@@ -2076,9 +2076,10 @@ SRV Records
 .. NOTE::
   This section is a work in progress.
 
-.. TODO
+.. TODO-doc
   - Why it is needed
 
+
 Security
 ========
 
@@ -2119,7 +2120,7 @@ victim would then include in their view of the chatroom history. Other servers
 in the chatroom would reject the invalid messages and potentially reject the
 victims messages as well since they depended on the invalid messages.
 
-.. TODO
+.. TODO-spec
   Track trustworthiness of HS or users based on if they try to pretend they
   haven't seen recent events, and fake a splitbrain... --M
 
@@ -2227,7 +2228,7 @@ standard error response of the form::
 The ``retry_after_ms`` key SHOULD be included to tell the client how long they
 have to wait in milliseconds before they can try again.
 
-.. TODO
+.. TODO-spec
   - Surely we should recommend an algorithm for the rate limiting, rather than letting every
     homeserver come up with their own idea, causing totally unpredictable performance over
     federated rooms?
@@ -2236,30 +2237,33 @@ have to wait in milliseconds before they can try again.
   - Lawful intercept + Key Escrow
   TODO Mark
 
+
 Policy Servers
 ==============
 .. NOTE::
   This section is a work in progress.
 
-.. TODO
+.. TODO-spec
   We should mention them in the Architecture section at least...
-  
+
+
 Content repository
 ==================
 .. NOTE::
   This section is a work in progress.
 
-.. TODO
+.. TODO-spec
   - path to upload
   - format for thumbnail paths, mention what it is protecting against.
   - content size limit and associated M_ERROR.
 
+
 Address book repository
 =======================
 .. NOTE::
   This section is a work in progress.
 
-.. TODO
+.. TODO-spec
   - format: POST(?) wodges of json, some possible processing, then return wodges of json on GET.
   - processing may remove dupes, merge contacts, pepper with extra info (e.g. matrix-ability of
     contacts), etc.