From 5f2062483a3e25f46568e197fd463bdc75d76fc7 Mon Sep 17 00:00:00 2001
From: Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
Date: Mon, 2 Jul 2018 13:47:32 +0200
Subject: [PATCH] ibb: Add documentation.

---
 src/ibb.rs    | 38 +++++++++++++++++++++++++++++++++-----
 src/macros.rs | 10 ++++++----
 2 files changed, 39 insertions(+), 9 deletions(-)

diff --git a/src/ibb.rs b/src/ibb.rs
index 50d47902..d67ffc6c 100644
--- a/src/ibb.rs
+++ b/src/ibb.rs
@@ -4,37 +4,65 @@
 // 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 helpers::Base64;
 use iq::IqSetPayload;
 
-generate_id!(StreamId);
+generate_id!(
+/// An identifier matching a stream.
+StreamId);
 
-generate_attribute!(Stanza, "stanza", {
+generate_attribute!(
+/// Which stanza type to use to exchange data.
+Stanza, "stanza", {
+    /// `<iq/>` gives a feedback on whether the chunk has been received or not,
+    /// which is useful in the case the recipient might not receive them in a
+    /// timely manner, or to do your own throttling based on the results.
     Iq => "iq",
+
+    /// `<message/>` can be faster, since it doesn’t require any feedback, but in
+    /// practice it will be throttled by the servers on the way.
     Message => "message",
 }, Default = Iq);
 
-generate_element!(Open, "open", IBB,
+generate_element!(
+/// Starts an In-Band Bytestream session with the given parameters.
+Open, "open", IBB,
 attributes: [
+    /// Maximum size in bytes for each chunk.
     block_size: u16 = "block-size" => required,
+
+    /// The identifier to be used to create a stream.
     sid: StreamId = "sid" => required,
+
+    /// Which stanza type to use to exchange data.
     stanza: Stanza = "stanza" => default,
 ]);
 
 impl IqSetPayload for Open {}
 
-generate_element_with_text!(Data, "data", IBB,
+generate_element_with_text!(
+/// Exchange a chunk of data in an open stream.
+Data, "data", IBB,
     [
+        /// Sequence number of this chunk, must wraparound after 65535.
         seq: u16 = "seq" => required,
+
+        /// The identifier of the stream on which data is being exchanged.
         sid: StreamId = "sid" => required
     ],
+    /// Vector of bytes to be exchanged.
     data: Base64<Vec<u8>>
 );
 
 impl IqSetPayload for Data {}
 
-generate_element!(Close, "close", IBB,
+generate_element!(
+/// Close an open stream.
+Close, "close", IBB,
 attributes: [
+    /// The identifier of the stream to be closed.
     sid: StreamId = "sid" => required,
 ]);
 
diff --git a/src/macros.rs b/src/macros.rs
index 971fe760..68e840c5 100644
--- a/src/macros.rs
+++ b/src/macros.rs
@@ -286,7 +286,8 @@ macro_rules! generate_empty_element {
 }
 
 macro_rules! generate_id {
-    ($elem:ident) => (
+    ($(#[$meta:meta])* $elem:ident) => (
+        $(#[$meta])*
         #[derive(Debug, Clone, PartialEq, Eq, Hash)]
         pub struct $elem(pub String);
         impl ::std::str::FromStr for $elem {
@@ -338,10 +339,10 @@ macro_rules! generate_elem_id {
 }
 
 macro_rules! generate_element_with_text {
-    ($(#[$meta:meta])* $elem:ident, $name:tt, $ns:ident, $text_ident:ident: $codec:ident < $text_type:ty >) => (
-        generate_element_with_text!($(#[$meta])* $elem, $name, $ns, [], $text_ident: $codec<$text_type>);
+    ($(#[$meta:meta])* $elem:ident, $name:tt, $ns:ident, $(#[$text_meta:meta])* $text_ident:ident: $codec:ident < $text_type:ty >) => (
+        generate_element_with_text!($(#[$meta])* $elem, $name, $ns, [], $(#[$text_meta])* $text_ident: $codec<$text_type>);
     );
-    ($(#[$meta:meta])* $elem:ident, $name:tt, $ns:ident, [$($(#[$attr_meta:meta])* $attr:ident: $attr_type:ty = $attr_name:tt => $attr_action:tt),*], $text_ident:ident: $codec:ident < $text_type:ty >) => (
+    ($(#[$meta:meta])* $elem:ident, $name:tt, $ns:ident, [$($(#[$attr_meta:meta])* $attr:ident: $attr_type:ty = $attr_name:tt => $attr_action:tt),*], $(#[$text_meta:meta])* $text_ident:ident: $codec:ident < $text_type:ty >) => (
         $(#[$meta])*
         #[derive(Debug, Clone)]
         pub struct $elem {
@@ -349,6 +350,7 @@ macro_rules! generate_element_with_text {
             $(#[$attr_meta])*
             pub $attr: $attr_type,
             )*
+            $(#[$text_meta])*
             pub $text_ident: $text_type,
         }