A bit of docs

1 files changed, 54 insertions, 5 deletions

diff --git a/src/ext/framework/configuration.rs b/src/ext/framework/configuration.rs
index 09874c8..4b0fc48 100644
--- a/src/ext/framework/configuration.rs
+++ b/src/ext/framework/configuration.rs
@@ -2,20 +2,52 @@ use std::default::Default;
 use ::client::http;
 
 pub struct Configuration {
+    #[doc(hidden)]
     pub depth: usize,
+    #[doc(hidden)]
     pub on_mention: Option<Vec<String>>,
+    #[doc(hidden)]
     pub allow_whitespace: bool,
+    #[doc(hidden)]
     pub prefix: Option<String>,
 }
 
 impl Configuration {
     /// The default depth of the message to check for commands. Defaults to 5.
+    /// This determines how "far" into a message to check for a valid command.
+    ///
+    /// # Examples
+    ///
+    /// If you set a depth of `1`, and make a command of `"music play"`, but
+    /// not a `"music"` command, then the former command will never be
+    /// triggered, as its "depth" is `2`.
     pub fn depth(mut self, depth: u8) -> Self {
         self.depth = depth as usize;
 
         self
     }
 
+    /// Whether or not to respond to commands initiated with a mention. Note
+    /// that this can be used in conjunction with [`prefix`].
+    ///
+    /// By default this is set to `false`.
+    ///
+    /// # Examples
+    ///
+    /// Setting this to `true` will allow the following types of mentions to be
+    /// responded to:
+    ///
+    /// ```ignore
+    /// <@245571012924538880> about
+    /// <@!245571012924538880> about
+    /// ```
+    ///
+    /// The former is a direct mention, while the latter is a nickname mention,
+    /// which aids mobile devices in determining whether to display a user's
+    /// nickname. It has no real meaning for your bot, and the library
+    /// encourages you to ignore differentiating between the two.
+    ///
+    /// [`prefix`]: #method.prefix
     pub fn on_mention(mut self, on_mention: bool) -> Self {
         if !on_mention {
             return self;
@@ -31,18 +63,27 @@ impl Configuration {
         self
     }
 
-    /// Whether to allow whitespace being optional between a mention and a
-    /// command.
+    /// Whether to allow whitespace being optional between a mention/prefix and
+    /// a command.
     ///
     /// **Note**: Defaults to `false`.
     ///
     /// # Examples
     ///
-    /// Setting this to `true` will allow this scenario to occur, while `false`
-    /// will not:
+    /// Setting this to `false` will _only_ allow this scenario to occur:
     ///
     /// ```ignore
-    /// <@BOT_ID>about
+    /// <@245571012924538880> about
+    /// !about
+    ///
+    /// // bot processes and executes the "about" command if it exists
+    /// ```
+    ///
+    /// while setting this to `true` will _also_ allow this scenario to occur:
+    ///
+    /// ```ignore
+    /// <@245571012924538880>about
+    /// ! about
     ///
     /// // bot processes and executes the "about" command if it exists
     /// ```
@@ -53,6 +94,8 @@ impl Configuration {
         self
     }
 
+    /// Sets the prefix to respond to. This can either be a single-char or
+    /// multi-char string.
     pub fn prefix<S: Into<String>>(mut self, prefix: S) -> Self {
         self.prefix = Some(prefix.into());
 
@@ -61,6 +104,12 @@ impl Configuration {
 }
 
 impl Default for Configuration {
+    /// Builds a default framework configuration, setting the following:
+    ///
+    /// - **allow_whitespace** to `false`
+    /// - **depth** to `5`
+    /// - **on_mention** to `false` (basically)
+    /// - **prefix** to `None`
     fn default() -> Configuration {
         Configuration {
             depth: 5,