Add missing docs, fix a bunch of bugs and inconsistencies.

src/lib.rs

@@ -2,9 +2,8 @@
 //! endpoint in the [Matrix](https://matrix.org/) client API specification. These types can be
 //! shared by client and server code.
 
-#![deny(missing_debug_implementations)]
+#![deny(missing_debug_implementations, missing_docs)]
 #![feature(associated_consts, proc_macro, try_from)]
-#![warn(missing_docs)]
 
 extern crate futures;
 extern crate hyper;

src/r0/room.rs

@@ -16,25 +16,39 @@ pub mod create_room {
         }
 
         request {
+            /// Extra keys to be added to the content of the `m.room.create`.
             #[serde(skip_serializing_if = "Option::is_none")]
             pub creation_content: Option<CreationContent>,
+            /// A list of user IDs to invite to the room.
+            ///
+            /// This will tell the server to invite everyone in the list to the newly created room.
             #[serde(skip_serializing_if = "Vec::is_empty")]
             #[serde(default)]
             pub invite: Vec<UserId>,
+            /// If this is included, an `m.room.name` event will be sent into the room to indicate
+            /// the name of the room.
             #[serde(skip_serializing_if = "Option::is_none")]
             pub name: Option<String>,
+            /// Convenience parameter for setting various default state events based on a preset.
             #[serde(skip_serializing_if = "Option::is_none")]
             pub preset: Option<RoomPreset>,
+            /// The desired room alias local part.
             #[serde(skip_serializing_if = "Option::is_none")]
             pub room_alias_name: Option<String>,
+            /// If this is included, an `m.room.topic` event will be sent into the room to indicate
+            /// the topic for the room.
             #[serde(skip_serializing_if = "Option::is_none")]
             pub topic: Option<String>,
+            /// A public visibility indicates that the room will be shown in the published room
+            /// list. A private visibility will hide the room from the published room list. Rooms
+            /// default to private visibility if this key is not included.
             #[serde(skip_serializing_if = "Option::is_none")]
-            pub visibility: Option<String>, // TODO: should be an enum ["public", "private"]
+            pub visibility: Option<Visibility>,
             // TODO: missing `invite_3pid`, `initial_state`
         }
 
         response {
+            /// The created room's ID.
             pub room_id: RoomId,
         }
     }
@@ -42,6 +56,9 @@ pub mod create_room {
     /// Extra options to be added to the `m.room.create` event.
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub struct CreationContent {
+        /// Whether users on other servers can join this room.
+        ///
+        /// Defaults to `true` if key does not exist.
         #[serde(rename="m.federate")]
         #[serde(skip_serializing_if = "Option::is_none")]
         pub federate: Option<bool>,
@@ -60,4 +77,15 @@ pub mod create_room {
         #[serde(rename="trusted_private_chat")]
         TrustedPrivateChat,
     }
+
+    /// Whether or not a newly created room will be listed in the room directory.
+    #[derive(Clone, Copy, Debug, Deserialize, Serialize)]
+    pub enum Visibility {
+        /// Indicates that the room will be shown in the published room list.
+        #[serde(rename = "public")]
+        Public,
+        /// Indicates that the room from the published room list.
+        #[serde(rename = "private")]
+        Private,
+    }
 }

src/r0/session.rs

@@ -13,40 +13,49 @@ pub mod login {
             rate_limited: true,
             requires_authentication: false,
         }
+
         request {
-            /// Password of the user
+            /// The user's password.
             pub password: String,
-            /// Medium of 3rd party login to use
+            /// When logging in using a third party identifier, the medium of the identifier.
             #[serde(skip_serializing_if = "Option::is_none")]
-            pub medium: Option<LoginMedium>,
+            pub medium: Option<Medium>,
-            /// Type of login to do
+            /// The authentication mechanism.
             #[serde(rename = "type")]
-            pub kind: LoginKind,
+            pub login_type: LoginType,
-            /// Localpart or full matrix user id of the user
+            /// The fully qualified user ID or just local part of the user ID.
             pub user: String,
-            /// 3rd party identifier for the user
+            /// Third party identifier for the user.
             #[serde(skip_serializing_if = "Option::is_none")]
             pub address: Option<String>
         }
+
         response {
+            /// An access token for the account.
             pub access_token: String,
+            /// The hostname of the homeserver on which the account has been registered.
             pub home_server: String,
+            /// A refresh token may be exchanged for a new access token using the /tokenrefresh API
+            /// endpoint.
             #[serde(skip_serializing_if = "Option::is_none")]
             pub refresh_token: Option<String>,
+            /// The fully-qualified Matrix ID that has been registered.
             pub user_id: String,
         }
     }
 
-    /// Possible login mediums for 3rd party ID
+    /// The medium of a third party identifier.
     #[derive(Clone, Debug, Deserialize, Serialize)]
-    pub enum LoginMedium {
+    pub enum Medium {
+        /// An email address.
         #[serde(rename = "email")]
         Email,
     }
 
-    /// Possible kinds of login
+    /// The authentication mechanism.
     #[derive(Clone, Debug, Deserialize, Serialize)]
-    pub enum LoginKind {
+    pub enum LoginType {
+        /// A password is supplied to authenticate.
         #[serde(rename = "m.login.password")]
         Password,
     }
@@ -65,7 +74,9 @@ pub mod logout {
             rate_limited: false,
             requires_authentication: true,
         }
+
         request {}
+
         response {}
     }
 }

src/r0/sync.rs

@@ -3,8 +3,8 @@
 /// [GET /_matrix/client/r0/rooms/{roomId}/state](https://matrix.org/docs/spec/client_server/r0.2.0.html#get-matrix-client-r0-rooms-roomid-state)
 pub mod get_state_events {
     use ruma_api_macros::ruma_api;
-    use ruma_identifiers::RoomId;
     use ruma_events::collections::only;
+    use ruma_identifiers::RoomId;
 
     ruma_api! {
         metadata {
@@ -15,11 +15,18 @@ pub mod get_state_events {
             rate_limited: false,
             requires_authentication: true,
         }
+
         request {
+            /// The room to look up the state for.
             #[ruma_api(path)]
             pub room_id: RoomId,
         }
+
         response {
+            /// If the user is a member of the room this will be the current state of the room as a
+            /// list of events. If the user has left the room then this will be the state of the
+            /// room when they left as a list of events.
+            #[ruma_api(body)]
             pub room_state: Vec<only::StateEvent>,
         }
     }
@@ -28,8 +35,8 @@ pub mod get_state_events {
 /// [GET /_matrix/client/r0/rooms/{roomId}/state/{eventType}](https://matrix.org/docs/spec/client_server/r0.2.0.html#get-matrix-client-r0-rooms-roomid-state-eventtype)
 pub mod get_state_events_for_empty_key {
     use ruma_api_macros::ruma_api;
-    use ruma_identifiers::RoomId;
     use ruma_events::EventType;
+    use ruma_identifiers::RoomId;
 
     ruma_api! {
         metadata {
@@ -40,15 +47,19 @@ pub mod get_state_events_for_empty_key {
             rate_limited: false,
             requires_authentication: true,
         }
+
         request {
-            /// The room to query for events
+            /// The room to look up the state for.
             #[ruma_api(path)]
             pub room_id: RoomId,
-            /// The type of state to look up
+            /// The type of state to look up.
             #[ruma_api(path)]
             pub event_type: EventType,
         }
+
         response {
+            /// The content of the state event.
+            #[ruma_api(body)]
             pub content: ::serde_json::Value,
         }
     }
@@ -68,8 +79,9 @@ pub mod get_state_events_for_key {
             rate_limited: false,
             requires_authentication: true,
         }
+
         request {
-            /// The room to look up the state in.
+            /// The room to look up the state for.
             #[ruma_api(path)]
             pub room_id: RoomId,
             /// The type of state to look up.
@@ -79,7 +91,10 @@ pub mod get_state_events_for_key {
             #[ruma_api(path)]
             pub state_key: String,
         }
+
         response {
+            /// The content of the state event.
+            #[ruma_api(body)]
             pub content: ::serde_json::Value,
         }
     }
@@ -88,8 +103,8 @@ pub mod get_state_events_for_key {
 /// [GET /_matrix/client/r0/rooms/{roomId}/members](https://matrix.org/docs/spec/client_server/r0.2.0.html#get-matrix-client-r0-rooms-roomid-members)
 pub mod get_member_events {
     use ruma_api_macros::ruma_api;
-    use ruma_identifiers::RoomId;
     use ruma_events::room::member::MemberEvent;
+    use ruma_identifiers::RoomId;
 
     ruma_api! {
         metadata {
@@ -103,12 +118,15 @@ pub mod get_member_events {
             // will return a 403 error is user is not a member of the
             // room anyway...
         }
+
         request {
-            /// The room to look up the state in.
+            /// The room to get the member events for.
             #[ruma_api(path)]
             pub room_id: RoomId,
         }
+
         response {
+            /// A list of member events.
             pub chunk: Vec<MemberEvent>
         }
     }
@@ -117,8 +135,8 @@ pub mod get_member_events {
 /// [GET /_matrix/client/r0/rooms/{roomId}/messages](https://matrix.org/docs/spec/client_server/r0.2.0.html#get-matrix-client-r0-rooms-roomid-messages)
 pub mod get_message_events {
     use ruma_api_macros::ruma_api;
-    use ruma_identifiers::RoomId;
     use ruma_events::collections::only;
+    use ruma_identifiers::RoomId;
 
     ruma_api! {
         metadata {
@@ -129,38 +147,50 @@ pub mod get_message_events {
             rate_limited: false,
             requires_authentication: true,
         }
+
         request {
-            // NOTE: The non-macro version of this call included two path params, where the spec only
+            /// The room to get events from.
-            // has one, room_id. I've followed the spec here. -- rschulman 6/30/2017
-            /// The room to look up the state in.
             #[ruma_api(path)]
             pub room_id: RoomId,
-            /// Required. The token to start returning events from. This token can be obtained from a 
+            /// The token to start returning events from.
-            /// prev_batch token returned for each room by the sync API, or from a start or end token 
+            ///
+            /// This token can be obtained from a
+            /// prev_batch token returned for each room by the sync API, or from a start or end token
             /// returned by a previous request to this endpoint.
             pub from: String,
-            /// The token to stop returning events at. This token can be obtained from a prev_batch 
+            /// The token to stop returning events at.
-            /// token returned for each room by the sync endpoint, or from a start or end token returned 
+            ///
+            /// This token can be obtained from a prev_batch
+            /// token returned for each room by the sync endpoint, or from a start or end token returned
             /// by a previous request to this endpoint.
             #[serde(skip_serializing_if = "Option::is_none")]
             pub to: Option<String>,
-            /// Required. The direction to return events from. One of: ["b", "f"]
+            /// The direction to return events from.
             pub dir: Direction,
-            /// The maximum number of events to return. Default: 10.
+            /// The maximum number of events to return.
+            ///
+            /// Default: 10.
             #[serde(skip_serializing_if = "Option::is_none")]
             pub limit: Option<u64>,
         }
+
         response {
+            /// The token the pagination starts from.
             pub start: String,
+            /// A list of room events.
             pub chunk: Vec<only::RoomEvent>,
+            /// The token the pagination ends at.
             pub end: String,
         }
     }
 
+    /// The direction to return events from.
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub enum Direction {
+        /// Return events backwards in time from the requested `from` token.
         #[serde(rename="b")]
         Backward,
+        /// Return events forwards in time from the requested `from` token.
         #[serde(rename="f")]
         Forward,
     }
@@ -168,12 +198,12 @@ pub mod get_message_events {
 
 /// [GET /_matrix/client/r0/sync](https://matrix.org/docs/spec/client_server/r0.2.0.html#get-matrix-client-r0-sync)
 pub mod sync_events {
-    use ruma_api_macros::ruma_api;
-    use ruma_events::collections::only;
-    use ruma_identifiers::RoomId;
-
     use std::collections::HashMap;
 
+    use ruma_api_macros::ruma_api;
+    use ruma_events::collections::{all, only};
+    use ruma_identifiers::RoomId;
+
     use r0::filter::FilterDefinition;
 
     ruma_api! {
@@ -185,21 +215,31 @@ pub mod sync_events {
             rate_limited: false,
             requires_authentication: true,
         }
+
         request {
+            /// A filter represented either as its full JSON definition or the ID of a saved filter.
             #[serde(skip_serializing_if = "Option::is_none")]
             pub filter: Option<Filter>,
+            /// A point in time to continue a sync from.
             #[serde(skip_serializing_if = "Option::is_none")]
             pub since: Option<String>,
+            /// Controls whether to include the full state for all rooms the user is a member of.
             #[serde(skip_serializing_if = "Option::is_none")]
             pub full_state: Option<bool>,
+            /// Controls whether the client is automatically marked as online by polling this API.
             #[serde(skip_serializing_if = "Option::is_none")]
             pub set_presence: Option<SetPresence>,
+            /// The maximum time to poll in milliseconds before returning this request.
             #[serde(skip_serializing_if = "Option::is_none")]
             pub timeout: Option<u64>,
         }
+
         response {
+            /// The batch token to supply in the `since` param of the next `/sync` request.
             pub next_batch: String,
+            /// Updates to rooms.
             pub rooms: Rooms,
+            /// Updates to the presence status of other users.
             pub presence: Presence,
         }
 
@@ -208,6 +248,7 @@ pub mod sync_events {
     /// Whether to set presence or not during sync.
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub enum SetPresence {
+        /// Do not set the presence of the user calling this API.
         #[serde(rename="offline")]
         Offline,
     }
@@ -221,79 +262,105 @@ pub mod sync_events {
         FilterId(String),
     }
 
-    /// Updates to rooms
+    /// Updates to rooms.
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub struct Rooms {
+        /// The rooms that the user has left or been banned from.
         pub leave: HashMap<RoomId, LeftRoom>,
+        /// The rooms that the user has joined.
         pub join: HashMap<RoomId, JoinedRoom>,
+        /// The rooms that the user has been invited to.
         pub invite: HashMap<RoomId, InvitedRoom>,
     }
 
-    /// Historical updates to left rooms
+    /// Historical updates to left rooms.
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub struct LeftRoom {
+        /// The timeline of messages and state changes in the room up to the point when the user
+        /// left.
         pub timeline: Timeline,
+        /// The state updates for the room up to the start of the timeline.
         pub state: State,
     }
 
-    /// Updates to joined rooms
+    /// Updates to joined rooms.
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub struct JoinedRoom {
+        /// Counts of unread notifications for this room.
         pub unread_notifications: UnreadNotificationsCount,
+        /// The timeline of messages and state changes in the room.
         pub timeline: Timeline,
+        /// Updates to the state, between the time indicated by the `since` parameter, and the start
+        /// of the `timeline` (or all state up to the start of the `timeline`, if `since` is not
+        /// given, or `full_state` is true).
         pub state: State,
+        /// The private data that this user has attached to this room.
         pub account_data: AccountData,
+        /// The ephemeral events in the room that aren't recorded in the timeline or state of the
+        /// room. e.g. typing.
         pub ephemeral: Ephemeral,
     }
 
     /// unread notifications count
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub struct UnreadNotificationsCount {
+        /// The number of unread notifications for this room with the highlight flag set.
         pub highlight_count: u64,
+        /// The total number of unread notifications for this room.
         pub notification_count: u64,
     }
 
-    /// timeline
+    /// Events in the room.
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub struct Timeline {
+        /// True if the number of events returned was limited by the `limit` on the filter.
         pub limited: bool,
+        /// A token that can be supplied to to the `from` parameter of the
+        /// `/rooms/{roomId}/messages` endpoint.
         pub prev_batch: String,
-        pub events: only::RoomEvent,
+        /// A list of events.
+        pub events: Vec<all::StateEvent>,
     }
 
-    /// state
+    /// State events in the room.
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub struct State {
-        pub events: only::StateEvent,
+        /// A list of state events.
+        pub events: Vec<only::StateEvent>,
     }
 
-    /// account data
+    /// The private data that this user has attached to this room.
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub struct AccountData {
-        pub events: only::Event,
+        /// A list of events.
+        pub events: Vec<only::Event>,
     }
 
-    /// ephemeral
+    /// Ephemeral events not recorded in the timeline or state of the room.
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub struct Ephemeral {
-        pub events: only::Event,
+        /// A list of events.
+        pub events: Vec<only::Event>,
     }
 
-    /// invited room updates
+    /// Updates to the rooms that the user has been invited to.
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub struct InvitedRoom {
+        /// The state of a room that the user has been invited to.
         pub invite_state: InviteState,
     }
 
-    /// invite state
+    /// The state of a room that the user has been invited to.
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub struct InviteState {
-        pub events: only::StateEvent,
+        /// A list of state events.
+        pub events: Vec<only::StateEvent>,
     }
 
-    /// presence
+    /// Updates to the presence status of other users.
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub struct Presence {
-        pub events: only::Event,
+        /// A list of events.
+        pub events: Vec<only::Event>,
     }
 }