doc

src/client/mod.rs

@@ -22,7 +22,9 @@ use self::auth::ClientAuth;
 mod bind;
 use self::bind::ClientBind;
 
+/// XMPP client connection and state
 pub struct Client {
+    /// The client's current Jabber-Id
     pub jid: Jid,
     state: ClientState,
 }
@@ -38,6 +40,10 @@ enum ClientState {
 }
 
 impl Client {
+    /// Start a new XMPP client
+    ///
+    /// Start polling the returned instance so that it will connect
+    /// and yield events.
     pub fn new(jid: &str, password: &str, handle: Handle) -> Result<Self, JidParseError> {
         let jid = try!(Jid::from_str(jid));
         let password = password.to_owned();

src/component/mod.rs

@@ -1,3 +1,6 @@
+//! Components in XMPP are services/gateways that are logged into an
+//! XMPP server under a JID consisting of just a domain name. They are
+//! allowed to use any user and resource identifiers in their stanzas.
 use std::mem::replace;
 use std::str::FromStr;
 use std::error::Error;
@@ -16,7 +19,9 @@ use super::event::Event;
 mod auth;
 use self::auth::ComponentAuth;
 
+/// Component connection to an XMPP server
 pub struct Component {
+    /// The component's Jabber-Id
     pub jid: Jid,
     state: ComponentState,
 }
@@ -32,6 +37,10 @@ enum ComponentState {
 }
 
 impl Component {
+    /// Start a new XMPP component
+    ///
+    /// Start polling the returned instance so that it will connect
+    /// and yield events.
     pub fn new(jid: &str, password: &str, server: &str, port: u16, handle: Handle) -> Result<Self, JidParseError> {
         let jid = try!(Jid::from_str(jid));
         let password = password.to_owned();

src/event.rs

@@ -1,13 +1,18 @@
 use minidom::Element;
 
+/// High-level event on the Stream implemented by Client and Component
 #[derive(Debug)]
 pub enum Event {
+    /// Stream is connected and initialized
     Online,
+    /// Stream end
     Disconnected,
+    /// Received stanza/nonza
     Stanza(Element),
 }
 
 impl Event {
+    /// `Online` event?
     pub fn is_online(&self) -> bool {
         match *self {
             Event::Online => true,
@@ -15,6 +20,7 @@ impl Event {
         }
     }
 
+    /// `Stanza` event?
     pub fn is_stanza(&self, name: &str) -> bool {
         match *self {
             Event::Stanza(ref stanza) => stanza.name() == name,
@@ -22,6 +28,7 @@ impl Event {
         }
     }
 
+    /// If this is a `Stanza` event, get its data
     pub fn as_stanza(&self) -> Option<&Element> {
         match *self {
             Event::Stanza(ref stanza) => Some(stanza),
@@ -29,6 +36,7 @@ impl Event {
         }
     }
 
+    /// If this is a `Stanza` event, unwrap into its data
     pub fn into_stanza(self) -> Option<Element> {
         match self {
             Event::Stanza(stanza) => Some(stanza),

src/lib.rs

@@ -1,3 +1,7 @@
+#![deny(unsafe_code, unused, missing_docs)]
+
+//! XMPP implemeentation with asynchronous I/O using Tokio.
+
 extern crate futures;
 extern crate tokio_core;
 extern crate tokio_io;

src/starttls.rs

@@ -11,10 +11,11 @@ use jid::Jid;
 use xmpp_codec::Packet;
 use xmpp_stream::XMPPStream;
 
-
+/// XMPP TLS XML namespace
 pub const NS_XMPP_TLS: &str = "urn:ietf:params:xml:ns:xmpp-tls";
 
 
+/// XMPP stream that switches to TLS if available in received features
 pub struct StartTlsClient<S: AsyncRead + AsyncWrite> {
     state: StartTlsClientState<S>,
     jid: Jid,

src/xmpp_codec.rs

@@ -1,3 +1,5 @@
+//! XML stream parser for XMPP
+
 use std;
 use std::default::Default;
 use std::iter::FromIterator;
@@ -15,17 +17,22 @@ use xml5ever::interface::Attribute;
 use bytes::{BytesMut, BufMut};
 use quick_xml::Writer as EventWriter;
 
-// const NS_XMLNS: &'static str = "http://www.w3.org/2000/xmlns/";
-
+/// Anything that can be sent or received on an XMPP/XML stream
 #[derive(Debug)]
 pub enum Packet {
+    /// General error (`InvalidInput`)
     Error(Box<std::error::Error>),
+    /// `<stream:stream>` start tag
     StreamStart(HashMap<String, String>),
+    /// A complete stanza or nonza
     Stanza(Element),
+    /// Plain text (think whitespace keep-alive)
     Text(String),
+    /// `</stream:stream>` closing tag
     StreamEnd,
 }
 
+/// Parser state
 struct ParserSink {
     // Ready stanzas, shared with XMPPCodec
     queue: Rc<RefCell<VecDeque<Packet>>>,
@@ -47,6 +54,7 @@ impl ParserSink {
         self.queue.borrow_mut().push_back(pkt);
     }
 
+    /// Lookup XML namespace declaration for given prefix (or no prefix)
     fn lookup_ns(&self, prefix: &Option<String>) -> Option<&str> {
         for nss in self.ns_stack.iter().rev() {
             if let Some(ns) = nss.get(prefix) {
@@ -166,6 +174,7 @@ impl TokenSink for ParserSink {
     // }
 }
 
+/// Stateful encoder/decoder for a bytestream from/to XMPP `Packet`
 pub struct XMPPCodec {
     /// Outgoing
     ns: Option<String>,
@@ -179,6 +188,7 @@ pub struct XMPPCodec {
 }
 
 impl XMPPCodec {
+    /// Constructor
     pub fn new() -> Self {
         let queue = Rc::new(RefCell::new(VecDeque::new()));
         let sink = ParserSink::new(queue.clone());
@@ -300,6 +310,7 @@ impl Encoder for XMPPCodec {
     }
 }
 
+/// Write XML-escaped text string
 pub fn write_text<W: Write>(text: &str, writer: &mut W) -> Result<(), std::fmt::Error> {
     write!(writer, "{}", escape(text))
 }

src/xmpp_stream.rs

@@ -1,3 +1,5 @@
+//! `XMPPStream` is the common container for all XMPP network connections
+
 use futures::{Poll, Stream, Sink, StartSend};
 use futures::sink::Send;
 use tokio_io::{AsyncRead, AsyncWrite};
@@ -8,16 +10,26 @@ use jid::Jid;
 use xmpp_codec::{XMPPCodec, Packet};
 use stream_start::StreamStart;
 
+/// <stream:stream> namespace
 pub const NS_XMPP_STREAM: &str = "http://etherx.jabber.org/streams";
 
+/// Wraps a `stream`
 pub struct XMPPStream<S> {
+    /// The local Jabber-Id
     pub jid: Jid,
+    /// Codec instance
     pub stream: Framed<S, XMPPCodec>,
+    /// `<stream:features/>` for XMPP version 1.0
     pub stream_features: Element,
+    /// Root namespace
+    ///
+    /// This is different for either c2s, s2s, or component
+    /// connections.
     pub ns: String,
 }
 
 impl<S: AsyncRead + AsyncWrite> XMPPStream<S> {
+    /// Constructor
     pub fn new(jid: Jid,
                stream: Framed<S, XMPPCodec>,
                ns: String,
@@ -25,15 +37,18 @@ impl<S: AsyncRead + AsyncWrite> XMPPStream<S> {
         XMPPStream { jid, stream, stream_features, ns }
     }
 
+    /// Send a `<stream:stream>` start tag
     pub fn start(stream: S, jid: Jid, ns: String) -> StreamStart<S> {
         let xmpp_stream = Framed::new(stream, XMPPCodec::new());
         StreamStart::from_stream(xmpp_stream, jid, ns)
     }
 
+    /// Unwraps the inner stream
     pub fn into_inner(self) -> S {
         self.stream.into_inner()
     }
 
+    /// Re-run `start()`
     pub fn restart(self) -> StreamStart<S> {
         Self::start(self.stream.into_inner(), self.jid, self.ns)
     }