From 22849f431db6fb479f5e17a2cabd9538d0084ead Mon Sep 17 00:00:00 2001
From: Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
Date: Wed, 8 Aug 2018 20:43:49 +0200
Subject: [PATCH] sm: Document this module, and add a test.

---
 src/sm.rs | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 71 insertions(+), 6 deletions(-)

diff --git a/src/sm.rs b/src/sm.rs
index 1fb2b94..e93aa24 100644
--- a/src/sm.rs
+++ b/src/sm.rs
@@ -4,35 +4,44 @@
 // 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/.
 
-#![allow(missing_docs)]
-
 use stanza_error::DefinedCondition;
 
 generate_element!(
+    /// Acknowledgement of the currently received stanzas.
     A, "a", SM,
     attributes: [
+        /// The last handled stanza.
         h: u32 = "h" => required,
     ]
 );
 
 impl A {
+    /// Generates a new `<a/>` element.
     pub fn new(h: u32) -> A {
         A { h }
     }
 }
 
-generate_attribute!(ResumeAttr, "resume", bool);
+generate_attribute!(
+    /// Whether to allow resumption of a previous stream.
+    ResumeAttr, "resume", bool
+);
 
 generate_element!(
+    /// Client request for enabling stream management.
     Enable, "enable", SM,
     attributes: [
+        /// The preferred resumption time in seconds by the client.
         // TODO: should be the infinite integer set ≥ 1.
         max: Option<u32> = "max" => optional,
+
+        /// Whether the client wants to be allowed to resume the stream.
         resume: ResumeAttr = "resume" => default,
     ]
 );
 
 impl Enable {
+    /// Generates a new `<enable/>` element.
     pub fn new() -> Self {
         Enable {
             max: None,
@@ -40,56 +49,86 @@ impl Enable {
         }
     }
 
+    /// Sets the preferred resumption time in seconds.
     pub fn with_max(mut self, max: u32) -> Self {
         self.max = Some(max);
         self
     }
 
+    /// Asks for resumption to be possible.
     pub fn with_resume(mut self) -> Self {
         self.resume = ResumeAttr::True;
         self
     }
 }
 
+generate_id!(
+    /// A random identifier used for stream resumption.
+    StreamId
+);
+
 generate_element!(
+    /// Server response once stream management is enabled.
     Enabled, "enabled", SM,
     attributes: [
-        id: Option<String> = "id" => optional,
+        /// A random identifier used for stream resumption.
+        id: Option<StreamId> = "id" => optional,
+
+        /// The preferred IP, domain, IP:port or domain:port location for
+        /// resumption.
         location: Option<String> = "location" => optional,
+
+        /// The preferred resumption time in seconds by the server.
         // TODO: should be the infinite integer set ≥ 1.
         max: Option<u32> = "max" => optional,
+
+        /// Whether stream resumption is allowed.
         resume: ResumeAttr = "resume" => default,
     ]
 );
 
 generate_element!(
+    /// A stream management error happened.
     Failed, "failed", SM,
     attributes: [
+        /// The last handled stanza.
         h: Option<u32> = "h" => optional,
     ],
     children: [
+        /// The error returned.
         // XXX: implement the * handling.
         error: Option<DefinedCondition> = ("*", XMPP_STANZAS) => DefinedCondition
     ]
 );
 
 generate_empty_element!(
+    /// Requests the currently received stanzas by the other party.
     R, "r", SM
 );
 
 generate_element!(
+    /// Requests a stream resumption.
     Resume, "resume", SM,
     attributes: [
+        /// The last handled stanza.
         h: u32 = "h" => required,
-        previd: String = "previd" => required,
+
+        /// The previous id given by the server on
+        /// [enabled](struct.Enabled.html).
+        previd: StreamId = "previd" => required,
     ]
 );
 
 generate_element!(
+    /// The response by the server for a successfully resumed stream.
     Resumed, "resumed", SM,
     attributes: [
+        /// The last handled stanza.
         h: u32 = "h" => required,
-        previd: String = "previd" => required,
+
+        /// The previous id given by the server on
+        /// [enabled](struct.Enabled.html).
+        previd: StreamId = "previd" => required,
     ]
 );
 
@@ -117,4 +156,30 @@ mod tests {
         let elem: Element = "<sm xmlns='urn:xmpp:sm:3'/>".parse().unwrap();
         StreamManagement::try_from(elem).unwrap();
     }
+
+    #[test]
+    fn resume() {
+        let elem: Element = "<enable xmlns='urn:xmpp:sm:3' resume='true'/>".parse().unwrap();
+        let enable = Enable::try_from(elem).unwrap();
+        assert_eq!(enable.max, None);
+        assert_eq!(enable.resume, ResumeAttr::True);
+
+        let elem: Element = "<enabled xmlns='urn:xmpp:sm:3' resume='true' id='coucou' max='600'/>".parse().unwrap();
+        let enabled = Enabled::try_from(elem).unwrap();
+        let previd = enabled.id.unwrap();
+        assert_eq!(enabled.resume, ResumeAttr::True);
+        assert_eq!(previd, StreamId(String::from("coucou")));
+        assert_eq!(enabled.max, Some(600));
+        assert_eq!(enabled.location, None);
+
+        let elem: Element = "<resume xmlns='urn:xmpp:sm:3' h='5' previd='coucou'/>".parse().unwrap();
+        let resume = Resume::try_from(elem).unwrap();
+        assert_eq!(resume.h, 5);
+        assert_eq!(resume.previd, previd);
+
+        let elem: Element = "<resumed xmlns='urn:xmpp:sm:3' h='5' previd='coucou'/>".parse().unwrap();
+        let resumed = Resumed::try_from(elem).unwrap();
+        assert_eq!(resumed.h, 5);
+        assert_eq!(resumed.previd, previd);
+    }
 }