A bit of docs

4 files changed, 68 insertions, 2 deletions

diff --git a/src/utils/builder/create_embed.rs b/src/utils/builder/create_embed.rs
index 4264175..fe15ed4 100644
--- a/src/utils/builder/create_embed.rs
+++ b/src/utils/builder/create_embed.rs
@@ -197,6 +197,7 @@ impl CreateEmbedAuthor {
 }
 
 impl Default for CreateEmbedAuthor {
+    /// Creates a builder with no default values.
     fn default() -> CreateEmbedAuthor {
         CreateEmbedAuthor(ObjectBuilder::new())
     }
@@ -259,6 +260,7 @@ impl CreateEmbedFooter {
 }
 
 impl Default for CreateEmbedFooter {
+    /// Creates a builder with no default values.
     fn default() -> CreateEmbedFooter {
         CreateEmbedFooter(ObjectBuilder::new())
     }
@@ -294,6 +296,7 @@ impl CreateEmbedThumbnail {
 }
 
 impl Default for CreateEmbedThumbnail {
+    /// Creates a builder with no default values.
     fn default() -> CreateEmbedThumbnail {
         CreateEmbedThumbnail(ObjectBuilder::new())
     }
@@ -329,6 +332,7 @@ impl CreateEmbedVideo {
 }
 
 impl Default for CreateEmbedVideo {
+    /// Creates a builder with no default values.
     fn default() -> CreateEmbedVideo {
         CreateEmbedVideo(ObjectBuilder::new())
     }
diff --git a/src/utils/builder/create_invite.rs b/src/utils/builder/create_invite.rs
index 55cc1bd..c8e175a 100644
--- a/src/utils/builder/create_invite.rs
+++ b/src/utils/builder/create_invite.rs
@@ -65,6 +65,7 @@ impl CreateInvite {
 }
 
 impl Default for CreateInvite {
+    /// Creates a builder with default values, setting `validate` to `null`.
     fn default() -> CreateInvite {
         CreateInvite(ObjectBuilder::new().insert("validate", Value::Null))
     }
diff --git a/src/utils/builder/execute_webhook.rs b/src/utils/builder/execute_webhook.rs
index d2a14aa..a434057 100644
--- a/src/utils/builder/execute_webhook.rs
+++ b/src/utils/builder/execute_webhook.rs
@@ -10,7 +10,47 @@ use std::default::Default;
 /// Refer to the documentation for [`execute_webhook`] on restrictions with
 /// execution payloads and its fields.
 ///
+/// # Examples
+///
+/// Creating two embeds, and then sending them as part of the delivery
+/// payload of [`Webhook::execute`]:
+///
+/// ```rust,no_run
+/// use serenity::client::http;
+/// use serenity::model::Embed;
+/// use serenity::utils::Colour;
+///
+/// let id = 245037420704169985;
+/// let token = "ig5AO-wdVWpCBtUUMxmgsWryqgsW3DChbKYOINftJ4DCrUbnkedoYZD0VOH1QLr-S3sV";
+///
+/// let webhook = http::get_webhook_with_token(id, token)
+///     .expect("valid webhook");
+///
+/// let website = Embed::fake(|e| e
+///     .title("The Rust Language Website")
+///     .description("Rust is a systems programming language.")
+///     .colour(Colour::from_rgb(222, 165, 132)));
+///
+/// let resources = Embed::fake(|e| e
+///     .title("Rust Resources")
+///     .description("A few resources to help with learning Rust")
+///     .colour(0xDEA584)
+///     .field(|f| f
+///         .inline(false)
+///         .name("The Rust Book")
+///         .value("A comprehensive resource for all topics related to Rust"))
+///     .field(|f| f
+///         .inline(false)
+///         .name("Rust by Example")
+///         .value("A collection of Rust examples on topics, useable in-browser")));
+///
+/// let _ = webhook.execute(|w| w
+///     .content("Here's some information on Rust:")
+///     .embeds(vec![website, resources]));
+/// ```
+///
 /// [`Webhook`]: ../model/struct.Webhook.html
+/// [`Webhook::execute`]: ../../model/struct.Webhook.html#method.execute
 /// [`execute_webhook`]: ../client/http/fn.execute_webhook.html
 pub struct ExecuteWebhook(pub ObjectBuilder);
 
@@ -21,11 +61,28 @@ impl ExecuteWebhook {
     }
 
     /// Set the content of the message.
+    ///
+    /// Note that when setting at least one embed via [`embeds`], this may be
+    /// omitted.
+    ///
+    /// [`embeds`]: #method.embeds
     pub fn content(self, content: &str) -> Self {
         ExecuteWebhook(self.0.insert("content", content))
     }
 
-    // Set the embeds associated with the message.
+    /// Set the embeds associated with the message.
+    ///
+    /// This should be used in combination with [`Embed::fake`], creating one
+    /// or more fake embeds to send to the API.
+    ///
+    /// # Examples
+    ///
+    /// Refer to the [struct-level documentation] for an example on how to use
+    /// embeds.
+    ///
+    /// [`Embed::fake`]: ../../model/struct.Embed.html#method.fake
+    /// [`Webhook::execute`]: ../../model/struct.Webhook.html#method.execute
+    /// [struct-level documentation]: #examples
     pub fn embeds(self, embeds: Vec<Value>) -> Self {
         ExecuteWebhook(self.0.insert("embeds", embeds))
     }
@@ -46,9 +103,12 @@ impl ExecuteWebhook {
 impl Default for ExecuteWebhook {
     /// Returns a default set of values for a [`Webhook`] execution.
     ///
-    /// The only default value is `tts` being set to `true`. In the event that
+    /// The only default value is [`tts`] being set to `true`. In the event that
     /// there is a bug that Discord defaults `tts` to `true`, at least
     /// serenity.rs won't be a part of it.
+    ///
+    /// [`Webhook`]: ../../model/struct.Webhook.html
+    /// [`tts`]: #method.tts
     fn default() -> ExecuteWebhook {
         ExecuteWebhook(ObjectBuilder::new().insert("tts", false))
     }
diff --git a/src/utils/builder/get_messages.rs b/src/utils/builder/get_messages.rs
index 4fdadff..d5088e8 100644
--- a/src/utils/builder/get_messages.rs
+++ b/src/utils/builder/get_messages.rs
@@ -75,6 +75,7 @@ impl GetMessages {
 }
 
 impl Default for GetMessages {
+    /// Creates a builder with no default values.
     fn default() -> GetMessages {
         GetMessages(BTreeMap::default())
     }