A bit of docs

2 files changed, 116 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,
diff --git a/src/ext/framework/mod.rs b/src/ext/framework/mod.rs
index c5e68ec..2c1ffb5 100644
--- a/src/ext/framework/mod.rs
+++ b/src/ext/framework/mod.rs
@@ -11,8 +11,29 @@ use std::thread;
 use ::client::Context;
 use ::model::Message;
 
+/// The type of command being received.
+///
+/// The [`Mention`] variant is emitted if the bot is being commanded via a
+/// mention (`<@USER_ID>` or `<@!USER_ID>`). This can only be emitted if
+/// [`Configuration::on_mention`] is set to `true`.
+///
+/// The [`Prefix`] variant is emitted if a message starts with the prefix set
+/// via [`Configuration::prefix`].
+///
+/// [`Mention`]: #variant.Mention
+/// [`Prefix`]: #variant.Prefix
+// This is public due to being leaked by [`command::positions`], which is used
+// in [`Framework::dispatch`]. It therefore is hidden from the docs, due to
+// having no use to users.
+//
+// [`Framework::dispatch`]: struct.Framework.html#method.dispatch
+// [`command::positions`]: command/fn.positions.html
 #[derive(Clone, Copy, Debug)]
+#[doc(hidden)]
 pub enum CommandType {
+    /// This is emitted if the bot is being commanded via a mention
+    /// (`<@USER_ID>` or `<@!USER_ID>`). This can only be emitted if
+    /// [`Configuration::on_mention`] is set to `true`.
     Mention,
     None,
     Prefix,
@@ -24,10 +45,51 @@ pub struct Framework {
     configuration: Configuration,
     commands: HashMap<String, InternalCommand>,
     checks: HashMap<String, Arc<Fn(&Context, &Message) -> bool + Send + Sync + 'static>>,
+    /// Whether the framework has been "initialized".
+    ///
+    /// The framework is initialized once one of the following occurs:
+    ///
+    /// - configuration has been set;
+    /// - a command handler has been set;
+    /// - a command check has been set.
+    ///
+    /// This is used internally to determine whether or not - in addition to
+    /// dispatching to the [`Client::on_message`] handler - to have the
+    /// framework check if a [`Event::MessageCreate`] should be processed by
+    /// itself.
+    ///
+    /// [`Client::on_message`]: ../../client/struct.Client.html#method.on_message
+    /// [`Event::MessageCreate`]: ../../model/enum.Event.html#variant.MessageCreate
     pub initialized: bool,
 }
 
 impl Framework {
+    /// Configures the framework, setting non-default values. All fields are
+    /// optional. Refer to [`Configuration::default`] for more information on
+    /// the default values.
+    ///
+    /// # Examples
+    ///
+    /// Configuring the framework for a [`Client`], setting the [`depth`] to 3,
+    /// [allowing whitespace], and setting the [`prefix`] to `"~"`:
+    ///
+    /// ```rust,no_run
+    /// use serenity::Client;
+    /// use std::env;
+    ///
+    /// let mut client = Client::login_bot(&env::var("DISCORD_TOKEN").unwrap());
+    /// client.with_framework(|f| f
+    ///     .configure(|c| c
+    ///         .depth(3)
+    ///         .allow_whitespace(true)
+    ///         .prefix("~")));
+    /// ```
+    ///
+    /// [`Client`]: ../../client/struct.Client.html
+    /// [`Configuration::default`]: struct.Configuration.html#method.default
+    /// [`depth`]: struct.Configuration.html#method.depth
+    /// [`prefix`]: struct.Configuration.html#method.prefix
+    /// [allowing whitespace]: struct.Configuration.html#method.allow_whitespace
     pub fn configure<F>(mut self, f: F) -> Self
         where F: FnOnce(Configuration) -> Configuration {
         self.configuration = f(self.configuration);