Add send_message rich embeds

1 files changed, 91 insertions, 6 deletions

diff --git a/src/client/context.rs b/src/client/context.rs
index 6443efa..fe69a57 100644
--- a/src/client/context.rs
+++ b/src/client/context.rs
@@ -884,18 +884,99 @@ impl Context {
 
     /// Sends a message to a [`Channel`].
     ///
-    /// Note that often a nonce is not required and can be omitted in most
-    /// situations.
+    /// Refer to the documentation for [`CreateMessage`] for more information
+    /// regarding message restrictions and requirements.
     ///
     /// **Note**: Message contents must be under 2000 unicode code points.
     ///
     /// # Example
     ///
+    /// Send a message with just the content `test`:
+    ///
     /// ```rust,ignore
     /// // assuming you are in a context
-    /// let _ = context.send_message(message.channel_id, "Hello!", "", false);
+    /// let _ = context.send_message(message.channel_id, |f| f.content("test"));
     /// ```
     ///
+    /// Send a message on `!ping` with a very descriptive [`Embed`]. This sends
+    /// a message content of `"Pong! Here's some info"`, with an embed with the
+    /// following attributes:
+    ///
+    /// - Dark gold in colour;
+    /// - A description of `"Information about the message just posted"`;
+    /// - A title of `"Message Information"`;
+    /// - A URL of `"https://rust-lang.org"`;
+    /// - An [author structure] containing an icon and the user's name;
+    /// - An inline [field structure] containing the message's content with a
+    ///   label;
+    /// - An inline field containing the channel's name with a label;
+    /// - A footer containing the current user's icon and name, saying that the
+    ///   information was generated by them.
+    ///
+    /// ```rust,no_run
+    /// use serenity::client::{STATE, Client, Context};
+    /// use serenity::model::{Channel, Message};
+    /// use serenity::utils::Colour;
+    /// use std::env;
+    ///
+    /// let mut client = Client::login_bot(&env::var("DISCORD_TOKEN").unwrap());
+    /// client.with_framework(|f| f
+    ///     .configure(|c| c.prefix("~"))
+    ///     .on("ping", ping));
+    ///
+    /// client.on_ready(|_context, ready| {
+    ///     println!("{} is connected!", ready.user.name);
+    /// });
+    ///
+    /// let _ = client.start();
+    ///
+    /// fn ping(context: Context, message: Message, _arguments: Vec<String>) {
+    ///     let state = STATE.lock().unwrap();
+    ///     let ch = state.find_channel(message.channel_id);
+    ///     let name = match ch {
+    ///         Some(Channel::Public(ch)) => ch.name.clone(),
+    ///         _ => "Unknown".to_owned(),
+    ///     };
+    ///
+    ///     let _ = context.send_message(message.channel_id, |m| m
+    ///         .content("Pong! Here's some info")
+    ///         .embed(|e| e
+    ///             .colour(Colour::dark_gold())
+    ///             .description("Information about the message just posted")
+    ///             .title("Message information")
+    ///             .url("https://rust-lang.org")
+    ///             .author(|mut a| {
+    ///                 a = a.name(&message.author.name);
+    ///
+    ///                 if let Some(avatar) = message.author.avatar_url() {
+    ///                     a = a.icon_url(&avatar);
+    ///                 }
+    ///
+    ///                 a
+    ///             })
+    ///             .field(|f| f
+    ///                 .inline(true)
+    ///                 .name("Message content:")
+    ///                 .value(&message.content))
+    ///             .field(|f| f
+    ///                 .inline(true)
+    ///                 .name("Channel name:")
+    ///                 .value(&name))
+    ///             .footer(|mut f| {
+    ///                 f = f.text(&format!("Generated by {}", state.user.name));
+    ///
+    ///                 if let Some(avatar) = state.user.avatar_url() {
+    ///                     f = f.icon_url(&avatar);
+    ///                 }
+    ///
+    ///                 f
+    ///             })));
+    /// }
+    /// ```
+    ///
+    /// Note that for most use cases, your embed layout will _not_ be this ugly.
+    /// This is an example of a very involved and conditional embed.
+    ///
     /// # Errors
     ///
     /// Returns a [`ClientError::MessageTooLong`] if the content of the message
@@ -904,13 +985,17 @@ impl Context {
     ///
     /// [`Channel`]: ../model/enum.Channel.html
     /// [`ClientError::MessageTooLong`]: enum.ClientError.html#variant.MessageTooLong
+    /// [`CreateMessage`]: ../utils/builder/struct.CreateMessage.html
+    /// [`Embed`]: ../model/struct.Embed.html
+    /// [author structure]: ../utils/builder/struct.CreateEmbedAuthor.html
+    /// [field structure]: ../utils/builder/struct.CreateEmbedField.html
     pub fn send_message<C, F>(&self, channel_id: C, f: F) -> Result<Message>
         where C: Into<ChannelId>, F: FnOnce(CreateMessage) -> CreateMessage {
         let map = f(CreateMessage::default()).0;
 
-        if let Some(ref content) = map.get(&"content".to_owned()) {
-            if let &&Value::String(ref content) = content {
-                if let Some(length_over) = Message::overflow_length(&content) {
+        if let Some(content) = map.get(&"content".to_owned()) {
+            if let Value::String(ref content) = *content {
+                if let Some(length_over) = Message::overflow_length(content) {
                     return Err(Error::Client(ClientError::MessageTooLong(length_over)));
                 }
             }