Add second generic parameter to events and add missing docs.

src/call/answer.rs

@@ -4,7 +4,7 @@ use RoomEvent;
 use super::SessionDescription;
 
 /// This event is sent by the callee when they wish to answer the call.
-pub type AnswerEvent = RoomEvent<AnswerEventContent>;
+pub type AnswerEvent = RoomEvent<AnswerEventContent, ()>;
 
 /// The payload of an `AnswerEvent`.
 #[derive(Debug, Deserialize, Serialize)]

src/call/candidates.rs

@@ -4,7 +4,7 @@ use RoomEvent;
 
 /// This event is sent by callers after sending an invite and by the callee after answering.
 /// Its purpose is to give the other party additional ICE candidates to try using to communicate.
-pub type CandidatesEvent = RoomEvent<CandidatesEventContent>;
+pub type CandidatesEvent = RoomEvent<CandidatesEventContent, ()>;
 
 /// The payload of a `CandidatesEvent`.
 #[derive(Debug, Deserialize, Serialize)]

src/call/hangup.rs

@@ -4,7 +4,7 @@ use RoomEvent;
 
 /// Sent by either party to signal their termination of the call. This can be sent either once the
 /// call has has been established or before to abort the call.
-pub type HangupEvent = RoomEvent<HangupEventContent>;
+pub type HangupEvent = RoomEvent<HangupEventContent, ()>;
 
 /// The payload of a `HangupEvent`.
 #[derive(Debug, Deserialize, Serialize)]

src/call/invite.rs

@@ -4,7 +4,7 @@ use RoomEvent;
 use super::SessionDescription;
 
 /// This event is sent by the caller when they wish to establish a call.
-pub type InviteEvent = RoomEvent<InviteEventContent>;
+pub type InviteEvent = RoomEvent<InviteEventContent, ()>;
 
 /// The payload of an `InviteEvent`.
 #[derive(Debug, Deserialize, Serialize)]

src/lib.rs

@@ -3,6 +3,7 @@
 
 #![feature(custom_derive, plugin)]
 #![plugin(serde_macros)]
+#![deny(missing_docs)]
 
 extern crate serde;
 extern crate serde_json;
@@ -20,16 +21,6 @@ pub mod stripped;
 pub mod tag;
 pub mod typing;
 
-/// A basic event.
-#[derive(Debug, Deserialize, Serialize)]
-pub struct Event<T> where T: Deserialize + Serialize {
-    pub content: T,
-    #[serde(rename="type")]
-    pub event_type: EventType,
-    /// Extra key-value pairs to be mixed into the top-level JSON representation of the event.
-    pub extra_content: Option<Value>,
-}
-
 /// The type of an event.
 #[derive(Debug, Deserialize, Serialize)]
 pub enum EventType {
@@ -81,34 +72,79 @@ pub enum EventType {
     Custom(String),
 }
 
-/// An event within the context of a room.
+/// A basic event.
 #[derive(Debug, Deserialize, Serialize)]
-pub struct RoomEvent<T> where T: Deserialize + Serialize {
-    pub content: T,
-    pub event_id: String,
-    /// Extra key-value pairs to be mixed into the top-level JSON representation of the event.
-    pub extra_content: Option<Value>,
+pub struct Event<C, E> where C: Deserialize + Serialize, E: Deserialize + Serialize {
+    /// Data specific to the event type.
+    pub content: C,
+
+    /// The type of the event.
     #[serde(rename="type")]
     pub event_type: EventType,
+
+    /// Extra top-level key-value pairs specific to this event type, but that are not under the
+    /// `content` field.
+    pub extra_content: E,
+}
+
+/// An event within the context of a room.
+#[derive(Debug, Deserialize, Serialize)]
+pub struct RoomEvent<C, E> where C: Deserialize + Serialize, E: Deserialize + Serialize {
+    /// Data specific to the event type.
+    pub content: C,
+
+    /// The unique identifier for the event.
+    pub event_id: String,
+
+    /// Extra top-level key-value pairs specific to this event type, but that are not under the
+    /// `content` field.
+    pub extra_content: E,
+
+    /// The type of the event.
+    #[serde(rename="type")]
+    pub event_type: EventType,
+
+    /// The unique identifier for the room associated with this event.
     pub room_id: String,
+
+    /// Additional key-value pairs not signed by the homeserver.
     pub unsigned: Option<Value>,
+
+    /// The unique identifier for the user associated with this event.
     #[serde(rename="sender")]
     pub user_id: String,
 }
 
 /// An event that describes persistent state about a room.
 #[derive(Debug, Deserialize, Serialize)]
-pub struct StateEvent<T> where T: Deserialize + Serialize {
-    pub content: T,
+pub struct StateEvent<C, E> where C: Deserialize + Serialize, E: Deserialize + Serialize {
+    /// Data specific to the event type.
+    pub content: C,
+
+    /// The unique identifier for the event.
     pub event_id: String,
+
+    /// The type of the event.
     #[serde(rename="type")]
     pub event_type: EventType,
-    /// Extra key-value pairs to be mixed into the top-level JSON representation of the event.
-    pub extra_content: Option<Value>,
-    pub prev_content: Option<T>,
+
+    /// Extra top-level key-value pairs specific to this event type, but that are not under the
+    /// `content` field.
+    pub extra_content: E,
+
+    /// The previous content for this state key, if any.
+    pub prev_content: Option<C>,
+
+    /// The unique identifier for the room associated with this event.
     pub room_id: String,
+
+    /// A key that determines which piece of room state the event represents.
     pub state_key: String,
+
+    /// Additional key-value pairs not signed by the homeserver.
     pub unsigned: Option<Value>,
+
+    /// The unique identifier for the user associated with this event.
     #[serde(rename="sender")]
     pub user_id: String,
 }

src/presence.rs

@@ -1,27 +1,30 @@
 //! Types for the *m.presence* event.
 
-use EventType;
+use Event;
 
 /// Informs the client of a user's presence state change.
-#[derive(Debug, Deserialize, Serialize)]
-pub struct PresenceEvent {
-    pub content: PresenceEventContent,
-    pub event_id: String,
-    #[serde(rename="type")]
-    pub event_type: EventType,
-}
+pub type PresenceEvent = Event<PresenceEventContent, PresenceEventExtraContent>;
 
 /// The payload of a `PresenceEvent`.
 #[derive(Debug, Deserialize, Serialize)]
 pub struct PresenceEventContent {
     /// The current avatar URL for this user.
     pub avatar_url: Option<String>,
+
+    /// Whether or not the user is currently active.
+    pub currently_active: bool,
+
     /// The current display name for this user.
     pub displayname: Option<String>,
+
     /// The last time since this used performed some action, in milliseconds.
     pub last_active_ago: Option<u64>,
+
     /// The presence state for this user.
     pub presence: PresenceState,
+
+    /// The unique identifier for the user associated with this event.
+    pub user_id: String,
 }
 
 /// A description of a user's connectivity and availability for chat.
@@ -29,12 +32,23 @@ pub struct PresenceEventContent {
 pub enum PresenceState {
     /// Connected to the service and available for chat.
     FreeForChat,
+
     /// Connected to the service but not visible to other users.
     Hidden,
+
     /// Disconnected from the service.
     Offline,
+
     /// Connected to the service.
     Online,
+
     /// Connected to the service but not available for chat.
     Unavailable,
 }
+
+/// Extra content for a `PresenceEvent`.
+#[derive(Debug, Deserialize, Serialize)]
+pub struct PresenceEventExtraContent {
+    /// The unique identifier for the event.
+    pub event_id: String,
+}

src/receipt.rs

@@ -2,16 +2,10 @@
 
 use std::collections::HashMap;
 
-use EventType;
+use Event;
 
 /// Informs the client of new receipts.
-#[derive(Debug, Deserialize, Serialize)]
-pub struct ReceiptEvent {
-    pub content: ReceiptEventContent,
-    #[serde(rename="type")]
-    pub event_type: EventType,
-    pub room_id: String,
-}
+pub type ReceiptEvent = Event<ReceiptEventContent, ReceiptEventExtraContent>;
 
 /// The payload of a `ReceiptEvent`.
 ///
@@ -37,3 +31,10 @@ pub struct Receipt {
     /// The timestamp the receipt was sent at.
     pub ts: u64,
 }
+
+/// Extra content for a `PresenceEvent`.
+#[derive(Debug, Deserialize, Serialize)]
+pub struct ReceiptEventExtraContent {
+    /// The unique identifier for the room associated with this event.
+    pub room_id: String,
+}

src/room/aliases.rs

@@ -3,7 +3,7 @@
 use StateEvent;
 
 /// Informs the room about what room aliases it has been given.
-pub type AliasesEvent = StateEvent<AliasesEventContent>;
+pub type AliasesEvent = StateEvent<AliasesEventContent, ()>;
 
 /// The payload of an `AliasesEvent`.
 #[derive(Debug, Deserialize, Serialize)]

src/room/avatar.rs

@@ -6,13 +6,17 @@ use super::ImageInfo;
 /// A picture that is associated with the room.
 ///
 /// This can be displayed alongside the room information.
-pub type AvatarEvent = StateEvent<AvatarEventContent>;
+pub type AvatarEvent = StateEvent<AvatarEventContent, ()>;
 
 /// The payload of an `AvatarEvent`.
 #[derive(Debug, Deserialize, Serialize)]
 pub struct AvatarEventContent {
+    /// Information about the avatar image.
     pub info: ImageInfo,
+    /// Information about the avatar thumbnail image.
     pub thumbnail_info: ImageInfo,
+    /// URL of the avatar thumbnail image.
     pub thumbnail_url: String,
+    /// URL of the avatar image.
     pub url: String,
 }

src/room/canonical_alias.rs

@@ -3,7 +3,7 @@
 use StateEvent;
 
 /// Informs the room as to which alias is the canonical one.
-pub type CanonicalAliasEvent = StateEvent<CanonicalAliasEventContent>;
+pub type CanonicalAliasEvent = StateEvent<CanonicalAliasEventContent, ()>;
 
 /// The payload of a `CanonicalAliasEvent`.
 #[derive(Debug, Deserialize, Serialize)]

src/room/create.rs

@@ -4,7 +4,7 @@ use StateEvent;
 
 /// This is the first event in a room and cannot be changed. It acts as the root of all other
 /// events.
-pub type CreateEvent = StateEvent<CreateEventContent>;
+pub type CreateEvent = StateEvent<CreateEventContent, ()>;
 
 /// The payload of a `CreateEvent`.
 #[derive(Debug, Deserialize, Serialize)]

src/room/guest_access.rs

@@ -6,11 +6,12 @@ use StateEvent;
 ///
 /// This event controls whether guest users are allowed to join rooms. If this event is absent,
 /// servers should act as if it is present and has the value `GuestAccess::Forbidden`.
-pub type GuestAccessEvent = StateEvent<GuestAccessEventContent>;
+pub type GuestAccessEvent = StateEvent<GuestAccessEventContent, ()>;
 
 /// The payload of a `GuestAccessEvent`.
 #[derive(Debug, Deserialize, Serialize)]
 pub struct GuestAccessEventContent {
+    /// A policy for guest user access to a room.
     pub guest_access: GuestAccess,
 }
 

src/room/history_visibility.rs

@@ -4,7 +4,7 @@ use StateEvent;
 
 /// This event controls whether a member of a room can see the events that happened in a room from
 /// before they joined.
-pub type HistoryVisibilityEvent = StateEvent<HistoryVisibilityEventContent>;
+pub type HistoryVisibilityEvent = StateEvent<HistoryVisibilityEventContent, ()>;
 
 /// The payload of a `HistoryVisibilityEvent`.
 #[derive(Debug, Deserialize, Serialize)]

src/room/join_rules.rs

@@ -3,7 +3,7 @@
 use StateEvent;
 
 /// Describes how users are allowed to join the room.
-pub type JoinRulesEvent = StateEvent<JoinRulesEventContent>;
+pub type JoinRulesEvent = StateEvent<JoinRulesEventContent, ()>;
 
 /// The payload of a `JoinRulesEvent`.
 #[derive(Debug, Deserialize, Serialize)]

src/room/member.rs

@@ -1,6 +1,6 @@
 //! Types for the *m.room.member* event.
 
-use EventType;
+use StateEvent;
 use stripped::StrippedState;
 
 /// The current membership state of a user in the room.
@@ -16,26 +16,20 @@ use stripped::StrippedState;
 /// This event may also include an *invite_room_state* key outside the *content* key. If present,
 /// this contains an array of `StrippedState` events. These events provide information on a few
 /// select state events such as the room name.
-#[derive(Debug, Deserialize, Serialize)]
-pub struct MemberEvent {
-    pub content: MemberEventContent,
-    pub event_id: String,
-    #[serde(rename="type")]
-    pub event_type: EventType,
-    pub invite_room_state: Option<Vec<StrippedState>>,
-    pub prev_content: Option<MemberEventContent>,
-    pub room_id: String,
-    pub state_key: String,
-    #[serde(rename="sender")]
-    pub user_id: String,
-}
+pub type MemberEvent = StateEvent<MemberEventContent, MemberEventExtraContent>;
 
 /// The payload of a `MemberEvent`.
 #[derive(Debug, Deserialize, Serialize)]
 pub struct MemberEventContent {
+    /// The avatar URL for this user.
     pub avatar_url: Option<String>,
+
+    /// The display name for this user.
     pub displayname: Option<String>,
+
+    /// The membership state of this user.
     pub membership: MembershipState,
+
     /// Warning: This field is not implemented yet and its type will change!
     pub third_party_invite: (), // TODO
 }
@@ -43,9 +37,25 @@ pub struct MemberEventContent {
 /// The membership state of a user.
 #[derive(Debug, Deserialize, Serialize)]
 pub enum MembershipState {
+    /// The user is banned.
     Ban,
+
+    /// The user has been invited.
     Invite,
+
+    /// The user has joined.
     Join,
+
+    /// The user has requested to join.
     Knock,
+
+    /// The user has left.
     Leave,
 }
+
+/// Extra content for a `MemberEvent`.
+#[derive(Debug, Deserialize, Serialize)]
+pub struct MemberEventExtraContent {
+    /// A subset of the state of the room at the time of the invite.
+    pub invite_room_state: Option<Vec<StrippedState>>,
+}

src/room/message.rs

@@ -4,31 +4,61 @@ use RoomEvent;
 use super::ImageInfo;
 
 /// A message sent to a room.
-pub type MessageEvent = RoomEvent<MessageEventContent>;
+pub type MessageEvent = RoomEvent<MessageEventContent, ()>;
 
 /// The message type of message event, e.g. `m.image` or `m.text`.
 #[derive(Debug, Deserialize, Serialize)]
 pub enum MessageType {
+    /// An audio message.
     Audio,
+
+    /// An emote message.
     Emote,
+
+    /// A file message.
     File,
+
+    /// An image message.
     Image,
+
+    /// A location message.
     Location,
+
+    /// A notice message.
     Notice,
+
+    /// A text message.
     Text,
+
+    /// A video message.
     Video,
 }
 
 /// The payload of a message event.
 #[derive(Debug, Deserialize, Serialize)]
 pub enum MessageEventContent {
+    /// An audio message.
     Audio(AudioMessageEventContent),
+
+    /// An emote message.
     Emote(EmoteMessageEventContent),
+
+    /// An file message.
     File(FileMessageEventContent),
+
+    /// An image message.
     Image(ImageMessageEventContent),
+
+    /// An location message.
     Location(LocationMessageEventContent),
+
+    /// An notice message.
     Notice(NoticeMessageEventContent),
+
+    /// An text message.
     Text(TextMessageEventContent),
+
+    /// An video message.
     Video(VideoMessageEventContent),
 }
 

src/room/mod.rs

@@ -20,8 +20,12 @@ pub mod topic;
 /// Metadata about an image.
 #[derive(Debug, Deserialize, Serialize)]
 pub struct ImageInfo {
+    /// The height of the image in pixels.
     pub height: u64,
+    /// The MIME type of the image, e.g. "image/png."
     pub mimetype: String,
+    /// The file size of the image in bytes.
     pub size: u64,
+    /// The width of the image in pixels.
     pub width: u64,
 }

src/room/name.rs

@@ -3,7 +3,7 @@
 use StateEvent;
 
 /// A human-friendly room name designed to be displayed to the end-user.
-pub type NameEvent = StateEvent<NameEventContent>;
+pub type NameEvent = StateEvent<NameEventContent, ()>;
 
 /// The payload of a `NameEvent`.
 #[derive(Debug, Deserialize, Serialize)]

src/room/power_levels.rs

@@ -5,17 +5,39 @@ use std::collections::HashMap;
 use StateEvent;
 
 /// Defines the power levels (privileges) of users in the room.
-pub type PowerLevelsEvent = StateEvent<PowerLevelsEventContent>;
+pub type PowerLevelsEvent = StateEvent<PowerLevelsEventContent, ()>;
 
 /// The payload of a `PowerLevelsEvent`.
 #[derive(Debug, Deserialize, Serialize)]
 pub struct PowerLevelsEventContent {
+    /// The level required to ban a user.
     pub ban: u64,
+
+    /// The level required to send specific event types.
+    ///
+    /// This is a mapping from event type to power level required.
     pub events: HashMap<String, u64>,
+
+    /// The default level required to send message events.
     pub events_default: u64,
+
+    /// The level required to invite a user.
+    pub invite: u64,
+
+    /// The level required to kick a user.
     pub kick: u64,
+
+    /// The level required to redact an event.
     pub redact: u64,
+
+    /// The default level required to send state events.
     pub state_default: u64,
+
+    /// The power levels for specific users.
+    ///
+    /// This is a mapping from `user_id` to power level for that user.
     pub users: HashMap<String, u64>,
+
+    /// The default power level for every user in the room.
     pub users_default: u64,
 }

src/room/redaction.rs

@@ -1,20 +1,9 @@
 //! Types for the *m.room.redaction* event.
 
-use EventType;
+use RoomEvent;
 
 /// A redaction of an event.
-#[derive(Debug, Deserialize, Serialize)]
-pub struct RedactionEvent {
-    pub content: RedactionEventContent,
-    pub event_id: String,
-    #[serde(rename="type")]
-    pub event_type: EventType,
-    /// The ID of the event that was redacted.
-    pub redacts: String,
-    pub room_id: String,
-    #[serde(rename="sender")]
-    pub user_id: String,
-}
+pub type RedactionEvent = RoomEvent<RedactionEventContent, RedactionEventExtraContent>;
 
 /// The payload of a `RedactionEvent`.
 #[derive(Debug, Deserialize, Serialize)]
@@ -22,3 +11,10 @@ pub struct RedactionEventContent {
     /// The reason for the redaction, if any.
     pub reason: Option<String>,
 }
+
+/// Extra content for a `RedactionEvent`.
+#[derive(Debug, Deserialize, Serialize)]
+pub struct RedactionEventExtraContent {
+    /// The ID of the event that was redacted.
+    pub redacts: String,
+}

src/room/third_party_invite.rs

@@ -7,12 +7,33 @@ use StateEvent;
 /// Acts as an *m.room.member* invite event, where there isn't a target user_id to invite. This
 /// event contains a token and a public key whose private key must be used to sign the token. Any
 /// user who can present that signature may use this invitation to join the target room.
-pub type ThirdPartyInviteEvent = StateEvent<ThirdPartyInviteEventContent>;
+pub type ThirdPartyInviteEvent = StateEvent<ThirdPartyInviteEventContent, ()>;
 
 /// The payload of a `ThirdPartyInviteEvent`.
 #[derive(Debug, Deserialize, Serialize)]
 pub struct ThirdPartyInviteEventContent {
+    /// A user-readable string which represents the user who has been invited.
     pub display_name: String,
+
+    /// A URL which can be fetched to validate whether the key has been revoked.
     pub key_validity_url: String,
+
+    /// A Base64-encoded Ed25519 key with which the token must be signed.
+    pub public_key: String,
+
+    /// Keys with which the token may be signed.
+    pub public_keys: Option<Vec<PublicKey>>,
+}
+
+/// A public key for signing a third party invite token.
+#[derive(Debug, Deserialize, Serialize)]
+pub struct PublicKey {
+    /// An optional URL which can be fetched to validate whether the key has been revoked.
+    ///
+    /// The URL must return a JSON object containing a boolean property named 'valid'.
+    /// If this URL is absent, the key must be considered valid indefinitely.
+    pub key_validity_url: Option<String>,
+
+    /// A Base64-encoded Ed25519 key with which the token must be signed.
     pub public_key: String,
 }

src/room/topic.rs

@@ -3,7 +3,7 @@
 use StateEvent;
 
 /// A topic is a short message detailing what is currently being discussed in the room.
-pub type TopicEvent = StateEvent<TopicEventContent>;
+pub type TopicEvent = StateEvent<TopicEventContent, ()>;
 
 /// The payload of a `TopicEvent`.
 #[derive(Debug, Deserialize, Serialize)]

src/stripped.rs

@@ -11,22 +11,39 @@ use room::name::NameEventContent;
 /// A stripped-down version of a state event that is included along with some other events.
 #[derive(Debug, Deserialize, Serialize)]
 pub enum StrippedState {
+    /// A stripped-down version of the *m.room.avatar* event.
     RoomAvatar(StrippedRoomAvatar),
+
+    /// A stripped-down version of the *m.room.canonical_alias* event.
     RoomCanonicalAlias(StrippedRoomCanonicalAlias),
+
+    /// A stripped-down version of the *m.room.join_rules* event.
     RoomJoinRules(StrippedRoomJoinRules),
+
+    /// A stripped-down version of the *m.room.name* event.
     RoomName(StrippedRoomName),
 }
 
 /// The general form of a `StrippedState`.
 #[derive(Debug, Deserialize, Serialize)]
-pub struct StrippedStateContent<T> where T: Deserialize + Serialize {
-    pub content: T,
+pub struct StrippedStateContent<C> where C: Deserialize + Serialize {
+    /// Data specific to the event type.
+    pub content: C,
+    /// The type of the event.
     #[serde(rename="type")]
     pub event_type: EventType,
+    /// A key that determines which piece of room state the event represents.
     pub state_key: String,
 }
 
+/// A stripped-down version of the *m.room.avatar* event.
 pub type StrippedRoomAvatar = StrippedStateContent<AvatarEventContent>;
+
+/// A stripped-down version of the *m.room.canonical_alias* event.
 pub type StrippedRoomCanonicalAlias = StrippedStateContent<CanonicalAliasEventContent>;
+
+/// A stripped-down version of the *m.room.join_rules* event.
 pub type StrippedRoomJoinRules = StrippedStateContent<JoinRulesEventContent>;
+
+/// A stripped-down version of the *m.room.name* event.
 pub type StrippedRoomName = StrippedStateContent<NameEventContent>;

src/tag.rs

@@ -5,7 +5,7 @@ use std::collections::HashMap;
 use Event;
 
 /// Informs the client of tags on a room.
-pub type TagEvent = Event<TagEventContent>;
+pub type TagEvent = Event<TagEventContent, ()>;
 
 /// The payload of a `TagEvent`.
 #[derive(Debug, Deserialize, Serialize)]
@@ -17,5 +17,6 @@ pub struct TagEventContent {
 /// Information about a tag.
 #[derive(Debug, Deserialize, Serialize)]
 pub struct TagInfo {
+    /// Value to use for lexicographically ordering rooms with this tag.
     pub order: Option<u64>,
 }

src/typing.rs

@@ -1,17 +1,9 @@
 //! Types for the *m.typing* event.
 
-use EventType;
+use Event;
 
 /// Informs the client of the list of users currently typing.
-#[derive(Debug, Deserialize, Serialize)]
-pub struct TypingEvent {
-    /// The payload.
-    pub content: TypingEventContent,
-    #[serde(rename="type")]
-    pub event_type: EventType,
-    /// The ID of the room associated with this event.
-    pub room_id: String,
-}
+pub type TypingEvent = Event<TypingEventContent, TypingEventExtraContent>;
 
 /// The payload of a `TypingEvent`.
 #[derive(Debug, Deserialize, Serialize)]
@@ -19,3 +11,10 @@ pub struct TypingEventContent {
     /// The list of user IDs typing in this room, if any.
     pub user_ids: Vec<String>,
 }
+
+/// Extra content for a `TypingEvent`.
+#[derive(Debug, Deserialize, Serialize)]
+pub struct TypingEventExtraContent {
+    /// The unique identifier for the room associated with this event.
+    pub room_id: String,
+}