From a4325c787ae256c20e7bafe925bbd92aad591fba Mon Sep 17 00:00:00 2001
From: Astro <astro@spaceboyz.net>
Date: Mon, 16 Mar 2020 00:34:46 +0100
Subject: [PATCH] tokio-xmpp: doc

---
 tokio-xmpp/src/client/mod.rs   | 31 ++++++++++++++++++++++++++++---
 tokio-xmpp/src/lib.rs          |  6 +++---
 tokio-xmpp/src/starttls.rs     |  2 ++
 tokio-xmpp/src/stream_start.rs |  2 ++
 tokio-xmpp/src/xmpp_stream.rs  |  7 +++++--
 5 files changed, 40 insertions(+), 8 deletions(-)

diff --git a/tokio-xmpp/src/client/mod.rs b/tokio-xmpp/src/client/mod.rs
index 9a6b2af3..b774b803 100644
--- a/tokio-xmpp/src/client/mod.rs
+++ b/tokio-xmpp/src/client/mod.rs
@@ -23,6 +23,9 @@ mod auth;
 mod bind;
 
 /// XMPP client connection and state
+///
+/// This implements the `futures` crate's [`Stream`](#impl-Stream) and
+/// [`Sink`](#impl-Sink<Packet>) traits.
 pub struct Client {
     state: ClientState,
     jid: Jid,
@@ -64,8 +67,8 @@ impl Client {
         client
     }
 
-    /// Set whether to reconnect (`true`) or end the stream (`false`)
-    /// when a connection to the server has ended.
+    /// Set whether to reconnect (`true`) or let the stream end
+    /// (`false`) when a connection to the server has ended.
     pub fn set_reconnect(&mut self, reconnect: bool) -> &mut Self {
         self.reconnect = reconnect;
         self
@@ -142,15 +145,34 @@ impl Client {
         self.send(Packet::Stanza(stanza)).await
     }
 
-    /// End connection
+    /// End connection by sending `</stream:stream>`
+    ///
+    /// You may expect the server to respond with the same. This
+    /// client will then drop its connection.
+    ///
+    /// Make sure to disable reconnect.
     pub async fn send_end(&mut self) -> Result<(), Error> {
         self.send(Packet::StreamEnd).await
     }
 }
 
+/// Incoming XMPP events
+///
+/// In an `async fn` you may want to use this with `use
+/// futures::stream::StreamExt;`
 impl Stream for Client {
     type Item = Event;
 
+    /// Low-level read on the XMPP stream, allowing the underlying
+    /// machinery to:
+    ///
+    /// * connect,
+    /// * starttls,
+    /// * authenticate,
+    /// * bind a session, and finally
+    /// * receive stanzas
+    ///
+    /// ...for your client
     fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context) -> Poll<Option<Self::Item>> {
         let state = replace(&mut self.state, ClientState::Invalid);
 
@@ -244,6 +266,9 @@ impl Stream for Client {
     }
 }
 
+/// Outgoing XMPP packets
+///
+/// See `send_stanza()` for an `async fn`
 impl Sink<Packet> for Client {
     type Error = Error;
 
diff --git a/tokio-xmpp/src/lib.rs b/tokio-xmpp/src/lib.rs
index f14ff6b2..54d4c6fd 100644
--- a/tokio-xmpp/src/lib.rs
+++ b/tokio-xmpp/src/lib.rs
@@ -1,10 +1,10 @@
-#![deny(unsafe_code, unused, missing_docs, bare_trait_objects)]
-
 //! XMPP implementation with asynchronous I/O using Tokio.
 
+#![deny(unsafe_code, unused, missing_docs, bare_trait_objects)]
+
 mod starttls;
 mod stream_start;
-pub mod xmpp_codec;
+mod xmpp_codec;
 pub use crate::xmpp_codec::Packet;
 mod event;
 mod happy_eyeballs;
diff --git a/tokio-xmpp/src/starttls.rs b/tokio-xmpp/src/starttls.rs
index de19eb04..49c52cb9 100644
--- a/tokio-xmpp/src/starttls.rs
+++ b/tokio-xmpp/src/starttls.rs
@@ -11,6 +11,8 @@ use crate::{Error, ProtocolError};
 /// XMPP TLS XML namespace
 pub const NS_XMPP_TLS: &str = "urn:ietf:params:xml:ns:xmpp-tls";
 
+/// Performs `<starttls/>` on an XMPPStream and returns a binary
+/// TlsStream.
 pub async fn starttls<S: AsyncRead + AsyncWrite + Unpin>(
     mut xmpp_stream: XMPPStream<S>,
 ) -> Result<TlsStream<S>, Error> {
diff --git a/tokio-xmpp/src/stream_start.rs b/tokio-xmpp/src/stream_start.rs
index 1fe16845..0dabbd6e 100644
--- a/tokio-xmpp/src/stream_start.rs
+++ b/tokio-xmpp/src/stream_start.rs
@@ -10,6 +10,8 @@ use crate::{Error, ProtocolError};
 
 const NS_XMPP_STREAM: &str = "http://etherx.jabber.org/streams";
 
+/// Sends a `<stream:stream>`, then wait for one from the server, and
+/// construct an XMPPStream.
 pub async fn start<S: AsyncRead + AsyncWrite + Unpin>(
     mut stream: Framed<S, XMPPCodec>,
     jid: Jid,
diff --git a/tokio-xmpp/src/xmpp_stream.rs b/tokio-xmpp/src/xmpp_stream.rs
index 5f00de11..733d342c 100644
--- a/tokio-xmpp/src/xmpp_stream.rs
+++ b/tokio-xmpp/src/xmpp_stream.rs
@@ -1,4 +1,4 @@
-//! `XMPPStream` is the common container for all XMPP network connections
+//! `XMPPStream` provides encoding/decoding for XMPP
 
 use futures::sink::Send;
 use futures::{sink::SinkExt, task::Poll, Sink, Stream};
@@ -17,7 +17,10 @@ use crate::Error;
 /// <stream:stream> namespace
 pub const NS_XMPP_STREAM: &str = "http://etherx.jabber.org/streams";
 
-/// Wraps a `stream`
+/// Wraps a binary stream (tokio's `AsyncRead + AsyncWrite`) to decode
+/// and encode XMPP packets.
+///
+/// Implements `Sink + Stream`
 pub struct XMPPStream<S: AsyncRead + AsyncWrite + Unpin> {
     /// The local Jabber-Id
     pub jid: Jid,