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

This commit is contained in:
Paul "LeoNerd" Evans 2014-09-30 18:11:24 +01:00
parent fbf6320614
commit 392dc8af59
1 changed files with 54 additions and 50 deletions

View File

@ -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 The ``localpart`` of a user ID may be a user name, or an opaque ID identifying
this user. They are case-insensitive. this user. They are case-insensitive.
.. TODO .. TODO-spec
- Need to specify precise grammar for Matrix IDs - Need to specify precise grammar for Matrix IDs
A "Home Server" is a server which provides C-S APIs and has the ability to 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 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. can be used in the next request to continue where the client left off.
.. TODO .. TODO-spec
How do we filter the event stream? How do we filter the event stream?
Do we ever return multiple events in a single request? Don't we get lots of request 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 setup RTT latency if we only do one event per request? Do we ever support streaming
@ -704,7 +704,7 @@ Rooms
Creation Creation
-------- --------
.. TODO kegan .. 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 To create a room, a client has to use the |createRoom|_ API. There are various
options which can be set when creating a room: options which can be set when creating a room:
@ -799,7 +799,7 @@ Modifying aliases
.. NOTE:: .. NOTE::
This section is a work in progress. This section is a work in progress.
.. TODO kegan .. TODO-doc kegan
- path to edit aliases - path to edit aliases
- PUT /directory/room/<room alias> { room_id : foo } - PUT /directory/room/<room alias> { room_id : foo }
- GET /directory/room/<room alias> { room_id : foo, servers: [a.com, b.com] } - GET /directory/room/<room alias> { room_id : foo, servers: [a.com, b.com] }
@ -811,11 +811,11 @@ Permissions
.. NOTE:: .. NOTE::
This section is a work in progress. This section is a work in progress.
.. TODO kegan .. TODO-doc kegan
- TODO: What is a power level? How do they work? Defaults / required levels for X. How do they change - 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. 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...) - 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. - 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. Link through to respective sections where necessary. How does this tie in with permissions, e.g.
give example of creating a read-only room. give example of creating a read-only room.
@ -845,7 +845,7 @@ defined in the following state events:
Joining rooms Joining rooms
------------- -------------
.. TODO kegan .. TODO-doc kegan
- TODO: What does the home server have to do to join a user to a room? - 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 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 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. - 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? - Outline invite join dance. What is it? Why is it required? How does it work?
- What does the home server have to do? - 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 Leaving rooms
------------- -------------
.. TODO kegan .. TODO-spec kegan
- TODO: Grace period before deletion? - TODO: Grace period before deletion?
- TODO: Under what conditions should a room NOT be purged? - 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 - |/rooms/<room_id>/initialSync|_ : A sync scoped to a single room. Presents
room and event information for this room only. room and event information for this room only.
.. TODO kegan .. TODO-doc kegan
- TODO: JSON response format for both types - TODO: JSON response format for both types
- TODO: when would you use global? when would you use scoped? - 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: Response format:
``[ { state event }, { state event }, ... ]`` ``[ { state event }, { state event }, ... ]``
Example: Example:
TODO TODO-doc
|/rooms/<room_id>/members|_ |/rooms/<room_id>/members|_
@ -1107,7 +1107,7 @@ There are several APIs provided to ``GET`` events for a room:
Response format: Response format:
``{ "start": "<token>", "end": "<token>", "chunk": [ { m.room.member event }, ... ] }`` ``{ "start": "<token>", "end": "<token>", "chunk": [ { m.room.member event }, ... ] }``
Example: Example:
TODO TODO-doc
|/rooms/<room_id>/messages|_ |/rooms/<room_id>/messages|_
Description: Description:
@ -1117,16 +1117,16 @@ There are several APIs provided to ``GET`` events for a room:
Response format: Response format:
``{ "start": "<token>", "end": "<token>" }`` ``{ "start": "<token>", "end": "<token>" }``
Example: Example:
TODO TODO-doc
|/rooms/<room_id>/initialSync|_ |/rooms/<room_id>/initialSync|_
Description: Description:
Get all relevant events for a room. This includes state events, paginated Get all relevant events for a room. This includes state events, paginated
non-state events and presence events. non-state events and presence events.
Response format: Response format:
`` { TODO } `` `` { TODO-doc } ``
Example: Example:
TODO TODO-doc
Redactions Redactions
---------- ----------
@ -1153,7 +1153,7 @@ Room Events
.. NOTE:: .. NOTE::
This section is a work in progress. This section is a work in progress.
.. TODO dave? .. TODO-doc dave?
- voip events? - voip events?
This specification outlines several standard event types, all of which are This specification outlines several standard event types, all of which are
@ -1232,7 +1232,7 @@ prefixed with ``m.``
Example: Example:
``{ "join_rule": "public" }`` ``{ "join_rule": "public" }``
Description: Description:
TODO : Use docs/models/rooms.rst TODO-doc : Use docs/models/rooms.rst
``m.room.power_levels`` ``m.room.power_levels``
Summary: Summary:
@ -1480,8 +1480,9 @@ the following:
- ``offline`` : The user is not connected to an event stream. - ``offline`` : The user is not connected to an event stream.
- ``free_for_chat`` : The user is generally willing to receive messages - ``free_for_chat`` : The user is generally willing to receive messages
moreso than default. moreso than default.
- ``hidden`` : TODO. Behaves as offline, but allows the user to see the - ``hidden`` : Behaves as offline, but allows the user to see the client
client state anyway and generally interact with client features. 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 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 many client devices they have connected. The home server should synchronise
@ -1509,7 +1510,7 @@ Transmission
.. NOTE:: .. NOTE::
This section is a work in progress. This section is a work in progress.
.. TODO: .. TODO-doc:
- Transmitted as an EDU. - Transmitted as an EDU.
- Presence lists determine who to send to. - 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 In the latter case, this allows for clients to display some minimal sense of
presence information in a user list for a room. presence information in a user list for a room.
Typing notifications Typing notifications
==================== ====================
.. NOTE:: .. NOTE::
This section is a work in progress. 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 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? - 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 - Timeouts. How do they work, who sets them and how do they expire. Does one
have priority over another? Give examples. 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 Voice over IP
============= =============
Matrix can also be used to set up VoIP calls. This is part of the core 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 setup for use on a call should be transferred and used for the call that
replaces it. replaces it.
Profiles Profiles
======== ========
.. NOTE:: .. NOTE::
This section is a work in progress. This section is a work in progress.
.. TODO .. TODO-doc
- Metadata extensibility - Metadata extensibility
- Changing profile info generates m.presence events ("presencelike") - Changing profile info generates m.presence events ("presencelike")
- keys on m.presence are optional, except presence which is required - keys on m.presence are optional, except presence which is required
@ -1712,9 +1720,10 @@ Identity
.. NOTE:: .. NOTE::
This section is a work in progress. This section is a work in progress.
.. TODO Dave .. TODO-doc Dave
- 3PIDs and identity server, functions - 3PIDs and identity server, functions
Federation Federation
========== ==========
@ -1884,10 +1893,9 @@ All PDUs have:
The maximum depth of the previous PDUs plus one. The maximum depth of the previous PDUs plus one.
.. TODO paul .. TODO-spec paul
[[TODO(paul): Update this structure so that 'pdu_id' is a two-element - Update this structure so that 'pdu_id' is a two-element [origin,ref] pair
[origin,ref] pair like the prev_pdus are]] like the prev_pdus are
For state updates: For state updates:
@ -1967,18 +1975,10 @@ keys exist to support this:
{..., {...,
"is_state":true, "is_state":true,
"state_key":TODO "state_key":TODO-doc
"power_level":TODO "power_level":TODO-doc
"prev_state_id":TODO "prev_state_id":TODO-doc
"prev_state_origin":TODO} "prev_state_origin":TODO-doc}
.. 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.]]
EDUs, by comparison to PDUs, do not have an ID, a context, or a list of 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 "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/ PUT .../send/:transaction_id/
Body: JSON encoding of a single Transaction 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 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 The destination name will be set to that of the receiving server itself. Each
@ -2068,7 +2068,7 @@ Backfilling
.. NOTE:: .. NOTE::
This section is a work in progress. This section is a work in progress.
.. TODO .. TODO-doc
- What it is, when is it used, how is it done - What it is, when is it used, how is it done
SRV Records SRV Records
@ -2076,9 +2076,10 @@ SRV Records
.. NOTE:: .. NOTE::
This section is a work in progress. This section is a work in progress.
.. TODO .. TODO-doc
- Why it is needed - Why it is needed
Security 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 in the chatroom would reject the invalid messages and potentially reject the
victims messages as well since they depended on the invalid messages. 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 Track trustworthiness of HS or users based on if they try to pretend they
haven't seen recent events, and fake a splitbrain... --M 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 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. 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 - 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 homeserver come up with their own idea, causing totally unpredictable performance over
federated rooms? federated rooms?
@ -2236,30 +2237,33 @@ have to wait in milliseconds before they can try again.
- Lawful intercept + Key Escrow - Lawful intercept + Key Escrow
TODO Mark TODO Mark
Policy Servers Policy Servers
============== ==============
.. NOTE:: .. NOTE::
This section is a work in progress. This section is a work in progress.
.. TODO .. TODO-spec
We should mention them in the Architecture section at least... We should mention them in the Architecture section at least...
Content repository Content repository
================== ==================
.. NOTE:: .. NOTE::
This section is a work in progress. This section is a work in progress.
.. TODO .. TODO-spec
- path to upload - path to upload
- format for thumbnail paths, mention what it is protecting against. - format for thumbnail paths, mention what it is protecting against.
- content size limit and associated M_ERROR. - content size limit and associated M_ERROR.
Address book repository Address book repository
======================= =======================
.. NOTE:: .. NOTE::
This section is a work in progress. 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. - 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 - processing may remove dupes, merge contacts, pepper with extra info (e.g. matrix-ability of
contacts), etc. contacts), etc.