From 0da3d55e40f783c54e65052a783e49b02555d69d Mon Sep 17 00:00:00 2001
From: Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
Date: Fri, 21 Apr 2017 01:06:30 +0100
Subject: [PATCH] First attempt at a documentation.

---
 src/lib.rs | 61 ++++++++++++++++++++++++++++++++++++++++--------------
 src/ns.rs  | 32 +++++++++++++++++++++++-----
 2 files changed, 73 insertions(+), 20 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index f7608cd7..dc8fcdb1 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,21 +1,51 @@
+//! A crate parsing common XMPP elements into Rust structures.
+//!
+//! The main entrypoint is `parse_message_payload`, it takes a minidom
+//! `Element` reference and optionally returns `Some(MessagePayload)` if the
+//! parsing succeeded.
+//!
+//! Parsed structs can then be manipulated internally, and serialised back
+//! before being sent over the wire.
+
 extern crate minidom;
-
-pub mod error;
-pub mod ns;
-
-pub mod body;
-pub mod disco;
-pub mod data_forms;
-pub mod media_element;
-pub mod ecaps2;
-pub mod jingle;
-pub mod ping;
-pub mod chatstates;
-pub mod ibb;
-pub mod receipts;
-
 use minidom::Element;
 
+/// Error type returned by every parser on failure.
+pub mod error;
+/// XML namespace definitions used through XMPP.
+pub mod ns;
+
+/// RFC 6120: Extensible Messaging and Presence Protocol (XMPP): Core
+pub mod body;
+
+/// XEP-0004: Data Forms
+pub mod data_forms;
+
+/// XEP-0030: Service Discovery
+pub mod disco;
+
+/// XEP-0047: In-Band Bytestreams
+pub mod ibb;
+
+/// XEP-0085: Chat State Notifications
+pub mod chatstates;
+
+/// XEP-0166: Jingle
+pub mod jingle;
+
+/// XEP-0184: Message Delivery Receipts
+pub mod receipts;
+
+/// XEP-0199: XMPP Ping
+pub mod ping;
+
+/// XEP-0221: Data Forms Media Element
+pub mod media_element;
+
+/// XEP-0390: Entity Capabilities 2.0
+pub mod ecaps2;
+
+/// Lists every known payload of a `<message/>`.
 #[derive(Debug)]
 pub enum MessagePayload {
     Body(body::Body),
@@ -23,6 +53,7 @@ pub enum MessagePayload {
     Receipt(receipts::Receipt),
 }
 
+/// Parse one of the payloads of a `<message/>` element, and return `Some` of a `MessagePayload` if parsing it succeeded, `None` otherwise.
 pub fn parse_message_payload(elem: &Element) -> Option<MessagePayload> {
     if let Ok(body) = body::parse_body(elem) {
         Some(MessagePayload::Body(body))
diff --git a/src/ns.rs b/src/ns.rs
index a1848e52..5bcf6d1e 100644
--- a/src/ns.rs
+++ b/src/ns.rs
@@ -1,9 +1,31 @@
+/// RFC 6120: Extensible Messaging and Presence Protocol (XMPP): Core
 pub const JABBER_CLIENT: &'static str = "jabber:client";
-pub const DISCO_INFO: &'static str = "http://jabber.org/protocol/disco#info";
+
+/// XEP-0004: Data Forms
 pub const DATA_FORMS: &'static str = "jabber:x:data";
-pub const MEDIA_ELEMENT: &'static str = "urn:xmpp:media-element";
-pub const JINGLE: &'static str = "urn:xmpp:jingle:1";
-pub const PING: &'static str = "urn:xmpp:ping";
-pub const CHATSTATES: &'static str = "http://jabber.org/protocol/chatstates";
+
+/// XEP-0030: Service Discovery
+pub const DISCO_INFO: &'static str = "http://jabber.org/protocol/disco#info";
+
+/// XEP-0047: In-Band Bytestreams
 pub const IBB: &'static str = "http://jabber.org/protocol/ibb";
+
+/// XEP-0085: Chat State Notifications
+pub const CHATSTATES: &'static str = "http://jabber.org/protocol/chatstates";
+
+/// XEP-0166: Jingle
+pub const JINGLE: &'static str = "urn:xmpp:jingle:1";
+
+/// XEP-0184: Message Delivery Receipts
 pub const RECEIPTS: &'static str = "urn:xmpp:receipts";
+
+/// XEP-0199: XMPP Ping
+pub const PING: &'static str = "urn:xmpp:ping";
+
+/// XEP-0221: Data Forms Media Element
+pub const MEDIA_ELEMENT: &'static str = "urn:xmpp:media-element";
+
+/// XEP-0390: Entity Capabilities 2.0
+pub const ECAPS2: &'static str = "urn:xmpp:caps";
+/// XEP-0390: Entity Capabilities 2.0
+pub const ECAPS2_OPTIMIZE: &'static str = "urn:xmpp:caps:optimize";