First attempt at a documentation.

Emmanuel Gil Peyrot created 8 years ago

Change summary

src/lib.rs | 45 ++++++++++++++++++++++++++++++++++++++-------
src/ns.rs  | 32 +++++++++++++++++++++++++++-----
2 files changed, 65 insertions(+), 12 deletions(-)

Detailed changes

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;
+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;
-pub mod disco;
+
+/// XEP-0004: Data Forms
 pub mod data_forms;
-pub mod media_element;
-pub mod ecaps2;
-pub mod jingle;
-pub mod ping;
-pub mod chatstates;
+
+/// 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;
 
-use minidom::Element;
+/// 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))

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";