presence: Finish to document this module.

src/presence.rs

@@ -5,8 +5,6 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-#![allow(missing_docs)]
-
 use try_from::TryFrom;
 use std::str::FromStr;
 use std::collections::BTreeMap;
@@ -22,12 +20,23 @@ use ns;
 /// Should be implemented on every known payload of a `<presence/>`.
 pub trait PresencePayload: TryFrom<Element> + Into<Element> {}
 
+/// Specifies the availability of an entity or resource.
 #[derive(Debug, Clone, PartialEq)]
 pub enum Show {
+    /// Not an actual show value, but an indication there is no show set.
     None,
+
+    /// The entity or resource is temporarily away.
     Away,
+
+    /// The entity or resource is actively interested in chatting.
     Chat,
+
+    /// The entity or resource is busy (dnd = "Do Not Disturb").
     Dnd,
+
+    /// The entity or resource is away for an extended period (xa = "eXtended
+    /// Away").
     Xa,
 }
 
@@ -70,22 +79,41 @@ impl IntoElements for Show {
     }
 }
 
-pub type Lang = String;
-pub type Status = String;
+type Lang = String;
+type Status = String;
 
-pub type Priority = i8;
+type Priority = i8;
 
+/// 
 #[derive(Debug, Clone, PartialEq)]
 pub enum Type {
     /// This value is not an acceptable 'type' attribute, it is only used
     /// internally to signal the absence of 'type'.
     None,
+
+    /// An error has occurred regarding processing of a previously sent
+    /// presence stanza; if the presence stanza is of type "error", it MUST
+    /// include an <error/> child element (refer to [XMPP‑CORE]).
     Error,
+
+    /// A request for an entity's current presence; SHOULD be generated only by
+    /// a server on behalf of a user.
     Probe,
+
+    /// The sender wishes to subscribe to the recipient's presence.
     Subscribe,
+
+    /// The sender has allowed the recipient to receive their presence.
     Subscribed,
+
+    /// The sender is no longer available for communication.
     Unavailable,
+
+    /// The sender is unsubscribing from the receiver's presence.
     Unsubscribe,
+
+    /// The subscription request has been denied or a previously granted
+    /// subscription has been canceled.
     Unsubscribed,
 }
 
@@ -132,17 +160,34 @@ impl IntoAttributeValue for Type {
 /// The main structure representing the `<presence/>` stanza.
 #[derive(Debug, Clone)]
 pub struct Presence {
+    /// The sender of this presence.
     pub from: Option<Jid>,
+
+    /// The recipient of this presence.
     pub to: Option<Jid>,
+
+    /// The identifier, unique on this stream, of this stanza.
     pub id: Option<String>,
+
+    /// The type of this presence stanza.
     pub type_: Type,
+
+    /// The availability of the sender of this presence.
     pub show: Show,
+
+    /// A localised list of statuses defined in this presence.
     pub statuses: BTreeMap<Lang, Status>,
+
+    /// The sender’s resource priority, if negative it won’t receive messages
+    /// that haven’t been directed to it.
     pub priority: Priority,
+
+    /// A list of payloads contained in this presence.
     pub payloads: Vec<Element>,
 }
 
 impl Presence {
+    /// Create a new presence of this type.
     pub fn new(type_: Type) -> Presence {
         Presence {
             from: None,
@@ -156,31 +201,40 @@ impl Presence {
         }
     }
 
+    /// Set the emitter of this presence, this should only be useful for
+    /// servers and components, as clients can only send presences from their
+    /// own resource (which is implicit).
     pub fn with_from(mut self, from: Option<Jid>) -> Presence {
         self.from = from;
         self
     }
 
+    /// Set the recipient of this presence, this is only useful for directed
+    /// presences.
     pub fn with_to(mut self, to: Option<Jid>) -> Presence {
         self.to = to;
         self
     }
 
+    /// Set the identifier for this presence.
     pub fn with_id(mut self, id: Option<String>) -> Presence {
         self.id = id;
         self
     }
 
+    /// Set the availability information of this presence.
     pub fn with_show(mut self, show: Show) -> Presence {
         self.show = show;
         self
     }
 
+    /// Set the priority of this presence.
     pub fn with_priority(mut self, priority: i8) -> Presence {
         self.priority = priority;
         self
     }
 
+    /// Set the payloads of this presence.
     pub fn with_payloads(mut self, payloads: Vec<Element>) -> Presence {
         self.payloads = payloads;
         self