From 92cdaaafcc2e24b93c52f521a418e9e78a5583bc Mon Sep 17 00:00:00 2001
From: Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
Date: Thu, 2 Aug 2018 22:16:55 +0200
Subject: [PATCH] pubsub: Document all of the modules.

---
 src/pubsub/event.rs  | 42 +++++++++++++++++++++++++++++++++++++++++-
 src/pubsub/mod.rs    | 42 +++++++++++++++++++++++++++++++++---------
 src/pubsub/pubsub.rs |  2 --
 3 files changed, 74 insertions(+), 12 deletions(-)

diff --git a/src/pubsub/event.rs b/src/pubsub/event.rs
index 14cec124..61b4396e 100644
--- a/src/pubsub/event.rs
+++ b/src/pubsub/event.rs
@@ -18,11 +18,17 @@ use data_forms::DataForm;
 
 use pubsub::{NodeName, ItemId, Subscription, SubscriptionId};
 
+/// One PubSub item from a node.
 #[derive(Debug, Clone)]
 pub struct Item {
-    pub payload: Option<Element>,
+    /// The identifier for this item, unique per node.
     pub id: Option<ItemId>,
+
+    /// The JID of the entity who published this item.
     pub publisher: Option<Jid>,
+
+    /// The actual content of this item.
+    pub payload: Option<Element>,
 }
 
 impl TryFrom<Element> for Item {
@@ -55,36 +61,70 @@ impl From<Item> for Element {
     }
 }
 
+/// Represents an event happening to a PubSub node.
 #[derive(Debug, Clone)]
 pub enum PubSubEvent {
     /*
     Collection {
     },
     */
+    /// This node’s configuration changed.
     Configuration {
+        /// The node affected.
         node: NodeName,
+
+        /// The new configuration of this node.
         form: Option<DataForm>,
     },
+
+    /// This node has been deleted, with an optional redirect to another node.
     Delete {
+        /// The node affected.
         node: NodeName,
+
+        /// The xmpp: URI of another node replacing this one.
         redirect: Option<String>,
     },
+
+    /// Some items have been published on this node.
     PublishedItems {
+        /// The node affected.
         node: NodeName,
+
+        /// The list of published items.
         items: Vec<Item>,
     },
+
+    /// Some items have been removed from this node.
     RetractedItems {
+        /// The node affected.
         node: NodeName,
+
+        /// The list of retracted items.
         items: Vec<ItemId>,
     },
+
+    /// All items of this node just got removed at once.
     Purge {
+        /// The node affected.
         node: NodeName,
     },
+
+    /// The user’s subscription to this node has changed.
     Subscription {
+        /// The node affected.
         node: NodeName,
+
+        /// The time at which this subscription will expire.
         expiry: Option<DateTime>,
+
+        /// The JID of the user affected.
         jid: Option<Jid>,
+
+        /// An identifier for this subscription.
         subid: Option<SubscriptionId>,
+
+        /// The state of this subscription.
         subscription: Option<Subscription>,
     },
 }
diff --git a/src/pubsub/mod.rs b/src/pubsub/mod.rs
index badf6729..5cf00d5c 100644
--- a/src/pubsub/mod.rs
+++ b/src/pubsub/mod.rs
@@ -4,6 +4,8 @@
 // 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/.
 
+//#![deny(missing_docs)]
+
 /// The `http://jabber.org/protocol/pubsub#event` protocol.
 pub mod event;
 
@@ -13,13 +15,35 @@ pub mod pubsub;
 pub use self::event::PubSubEvent;
 pub use self::pubsub::PubSub;
 
-generate_id!(NodeName);
-generate_id!(ItemId);
-generate_id!(SubscriptionId);
+generate_id!(
+    /// The name of a PubSub node, used to identify it on a JID.
+    NodeName
+);
 
-generate_attribute!(Subscription, "subscription", {
-    None => "none",
-    Pending => "pending",
-    Subscribed => "subscribed",
-    Unconfigured => "unconfigured",
-}, Default = None);
+generate_id!(
+    /// The identifier of an item, which is unique per node.
+    ItemId
+);
+
+generate_id!(
+    /// The identifier of a subscription to a PubSub node.
+    SubscriptionId
+);
+
+generate_attribute!(
+    /// The state of a subscription to a node.
+    Subscription, "subscription", {
+        /// The user is not subscribed to this node.
+        None => "none",
+
+        /// The user’s subscription to this node is still pending.
+        Pending => "pending",
+
+        /// The user is subscribed to this node.
+        Subscribed => "subscribed",
+
+        /// The user’s subscription to this node will only be valid once
+        /// configured.
+        Unconfigured => "unconfigured",
+    }, Default = None
+);
diff --git a/src/pubsub/pubsub.rs b/src/pubsub/pubsub.rs
index 8ecb89b6..52f51007 100644
--- a/src/pubsub/pubsub.rs
+++ b/src/pubsub/pubsub.rs
@@ -4,8 +4,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/.
 
-#![deny(missing_docs)]
-
 use try_from::TryFrom;
 
 use minidom::Element;