From 0b97510b08e344f76005cbac2f292d2b0dd75a72 Mon Sep 17 00:00:00 2001
From: lumi <lumi@pew.im>
Date: Tue, 21 Feb 2017 14:25:00 +0100
Subject: [PATCH] add documentation to Jid

---
 src/jid.rs | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)

diff --git a/src/jid.rs b/src/jid.rs
index cf35960..bcbeecd 100644
--- a/src/jid.rs
+++ b/src/jid.rs
@@ -4,15 +4,26 @@ use std::convert::Into;
 
 use std::str::FromStr;
 
+/// An error that signifies that a `Jid` cannot be parsed from a string.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum JidParseError {
     NoDomain,
 }
 
+/// A struct representing a Jabber ID.
+///
+/// A Jabber ID is composed of 3 components, of which 2 are optional:
+///
+///  - A node/name, `node`, which is the optional part before the @.
+///  - A domain, `domain`, which is the mandatory part after the @ but before the /.
+///  - A resource, `resource`, which is the optional part after the /.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Jid {
+    /// The node part of the Jabber ID, if it exists, else None.
     pub node: Option<String>,
+    /// The domain of the Jabber ID.
     pub domain: String,
+    /// The resource of the Jabber ID, if it exists, else None.
     pub resource: Option<String>,
 }
 
@@ -105,6 +116,21 @@ impl FromStr for Jid {
 }
 
 impl Jid {
+    /// Constructs a Jabber ID containing all three components.
+    ///
+    /// This is of the form `node`@`domain`/`resource`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use xmpp::jid::Jid;
+    ///
+    /// let jid = Jid::full("node", "domain", "resource");
+    ///
+    /// assert_eq!(jid.node, Some("node".to_owned()));
+    /// assert_eq!(jid.domain, "domain".to_owned());
+    /// assert_eq!(jid.resource, Some("resource".to_owned()));
+    /// ```
     pub fn full<NS, DS, RS>(node: NS, domain: DS, resource: RS) -> Jid
         where NS: Into<String>
             , DS: Into<String>
@@ -116,6 +142,21 @@ impl Jid {
         }
     }
 
+    /// Constructs a Jabber ID containing only the `node` and `domain` components.
+    ///
+    /// This is of the form `node`@`domain`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use xmpp::jid::Jid;
+    ///
+    /// let jid = Jid::bare("node", "domain");
+    ///
+    /// assert_eq!(jid.node, Some("node".to_owned()));
+    /// assert_eq!(jid.domain, "domain".to_owned());
+    /// assert_eq!(jid.resource, None);
+    /// ```
     pub fn bare<NS, DS>(node: NS, domain: DS) -> Jid
         where NS: Into<String>
             , DS: Into<String> {
@@ -126,6 +167,21 @@ impl Jid {
         }
     }
 
+    /// Constructs a Jabber ID containing only a `domain`.
+    ///
+    /// This is of the form `domain`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use xmpp::jid::Jid;
+    ///
+    /// let jid = Jid::domain("domain");
+    ///
+    /// assert_eq!(jid.node, None);
+    /// assert_eq!(jid.domain, "domain".to_owned());
+    /// assert_eq!(jid.resource, None);
+    /// ```
     pub fn domain<DS>(domain: DS) -> Jid
         where DS: Into<String> {
         Jid {
@@ -135,6 +191,21 @@ impl Jid {
         }
     }
 
+    /// Constructs a Jabber ID containing the `domain` and `resource` components.
+    ///
+    /// This is of the form `domain`/`resource`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use xmpp::jid::Jid;
+    ///
+    /// let jid = Jid::domain_with_resource("domain", "resource");
+    ///
+    /// assert_eq!(jid.node, None);
+    /// assert_eq!(jid.domain, "domain".to_owned());
+    /// assert_eq!(jid.resource, Some("resource".to_owned()));
+    /// ```
     pub fn domain_with_resource<DS, RS>(domain: DS, resource: RS) -> Jid
         where DS: Into<String>
             , RS: Into<String> {