diff --git a/src/builder/create_embed.rs b/src/builder/create_embed.rs index ff4e2c4bf06..00999361fe8 100644 --- a/src/builder/create_embed.rs +++ b/src/builder/create_embed.rs @@ -2,7 +2,7 @@ //! //! This is a set of embed builders for rich embeds. //! -//! These are used in the [`Context::send_message`] and +//! These are used in the [`ChannelId::send_message`] and //! [`ExecuteWebhook::embeds`] methods, both as part of builders. //! //! The only builder that should be exposed is [`CreateEmbed`]. The rest of @@ -10,7 +10,7 @@ //! //! Documentation for embeds can be found [here]. //! -//! [`Context::send_message`]: ../client/struct.Context.html#method.send_message +//! [`ChannelId::send_message`]: ../model/struct.ChannelId.html#method.send_message //! [`CreateEmbed`]: struct.CreateEmbed.html //! [`ExecuteWebhook::embeds`]: struct.ExecuteWebhook.html#method.embeds //! [here]: https://discordapp.com/developers/docs/resources/channel#embed-object @@ -25,14 +25,14 @@ use ::model::Embed; use ::utils::Colour; /// A builder to create a fake [`Embed`] object, for use with the -/// [`Context::send_message`] and [`ExecuteWebhook::embeds`] methods. +/// [`ChannelId::send_message`] and [`ExecuteWebhook::embeds`] methods. /// /// # Examples /// -/// Refer to the documentation for [`Context::send_message`] for a very in-depth +/// Refer to the documentation for [`ChannelId::send_message`] for a very in-depth /// example on how to use this. /// -/// [`Context::send_message`]: ../client/struct.Context.html#method.send_message +/// [`ChannelId::send_message`]: ../model/struct.ChannelId.html#method.send_message /// [`Embed`]: ../model/struct.Embed.html /// [`ExecuteWebhook::embeds`]: struct.ExecuteWebhook.html#method.embeds #[derive(Clone, Debug)] diff --git a/src/builder/create_invite.rs b/src/builder/create_invite.rs index 98fc2b940bb..bd76ed8451c 100644 --- a/src/builder/create_invite.rs +++ b/src/builder/create_invite.rs @@ -2,7 +2,7 @@ use serde_json::Value; use std::default::Default; use ::internal::prelude::*; -/// A builder to create a [`RichInvite`] for use via [`Context::create_invite`]. +/// A builder to create a [`RichInvite`] for use via [`GuildChannel::create_invite`]. /// /// This is a structured and cleaner way of creating an invite, as all /// parameters are optional. @@ -52,7 +52,7 @@ use ::internal::prelude::*; /// }); /// ``` /// -/// [`Context::create_invite`]: ../client/struct.Context.html#method.create_invite +/// [`GuildChannel::create_invite`]: ../model/struct.GuildChannel.html#method.create_invite /// [`RichInvite`]: ../model/struct.Invite.html #[derive(Clone, Debug)] pub struct CreateInvite(pub JsonMap); diff --git a/src/builder/create_message.rs b/src/builder/create_message.rs index 14be4ca803e..e9e8bf581c6 100644 --- a/src/builder/create_message.rs +++ b/src/builder/create_message.rs @@ -3,7 +3,7 @@ use ::model::ReactionType; use ::internal::prelude::*; /// A builder to specify the contents of an [`http::send_message`] request, -/// primarily meant for use through [`Context::send_message`]. +/// primarily meant for use through [`ChannelId::send_message`]. /// /// There are two situations where different field requirements are present: /// @@ -12,7 +12,7 @@ use ::internal::prelude::*; /// set. /// /// Note that if you only need to send the content of a message, without -/// specifying other fields, then [`Context::say`] may be a more preferable +/// specifying other fields, then [`ChannelId::say`] may be a more preferable /// option. /// /// # Examples @@ -32,8 +32,8 @@ use ::internal::prelude::*; /// .description("With a description"))); /// ``` /// -/// [`Context::say`]: ../client/struct.Context.html#method.say -/// [`Context::send_message`]: ../client/struct.Context.html#method.send_message +/// [`ChannelId::say`]: ../model/struct.ChannelId.html#method.say +/// [`ChannelId::send_message`]: ../model/struct.ChannelId.html#method.send_message /// [`content`]: #method.content /// [`embed`]: #method.embed /// [`http::send_message`]: ../http/fn.send_message.html diff --git a/src/builder/edit_channel.rs b/src/builder/edit_channel.rs index 2bf89798b08..9d859c7184e 100644 --- a/src/builder/edit_channel.rs +++ b/src/builder/edit_channel.rs @@ -1,11 +1,6 @@ use ::internal::prelude::*; -/// A builder to edit a [`GuildChannel`] for use via one of a couple methods. -/// -/// These methods are: -/// -/// - [`Context::edit_channel`] -/// - [`GuildChannel::edit`] +/// A builder to edit a [`GuildChannel`] for use via [`GuildChannel::edit`] /// /// Defaults are not directly provided by the builder itself. /// @@ -20,7 +15,6 @@ use ::internal::prelude::*; /// } /// ``` /// -/// [`Context::edit_channel`]: ../client/struct.Context.html#method.edit_channel /// [`GuildChannel`]: ../model/struct.GuildChannel.html /// [`GuildChannel::edit`]: ../model/struct.GuildChannel.html#method.edit #[derive(Clone, Debug, Default)] diff --git a/src/builder/edit_guild.rs b/src/builder/edit_guild.rs index c01b8ea816e..e74e54e17ba 100644 --- a/src/builder/edit_guild.rs +++ b/src/builder/edit_guild.rs @@ -2,14 +2,13 @@ use ::internal::prelude::*; use ::model::{ChannelId, Region, UserId, VerificationLevel}; /// A builder to optionally edit certain fields of a [`Guild`]. This is meant -/// for usage with [`Context::edit_guild`] and [`LiveGuild::edit`]. +/// for usage with [`Guild::edit`]. /// /// **Note**: Editing a guild requires that the current user have the /// [Manage Guild] permission. /// -/// [`Context::edit_guild`]: ../client/struct.Context.html +/// [`Guild::edit`]: ../model/struct.Guild.html#method.edit /// [`Guild`]: ../model/struct.Guild.html -/// [`LiveGuild::edit`]: ../model/struct.LiveGuild.html#method.edit /// [Manage Guild]: ../model/permissions/constant.MANAGE_GUILD.html #[derive(Clone, Debug, Default)] pub struct EditGuild(pub Map); diff --git a/src/builder/edit_member.rs b/src/builder/edit_member.rs index 044d8f24031..3fce146fb6b 100644 --- a/src/builder/edit_member.rs +++ b/src/builder/edit_member.rs @@ -2,9 +2,8 @@ use ::model::{ChannelId, RoleId}; use ::internal::prelude::*; /// A builder which edits the properties of a [`Member`], to be used in -/// conjunction with [`Context::edit_member`] and [`Member::edit`]. +/// conjunction with [`Member::edit`]. /// -/// [`Context::edit_member`]: ../client/struct.Context.html#method.edit_member /// [`Member`]: ../model/struct.Member.html /// [`Member::edit`]: ../model/struct.Member.html#method.edit #[derive(Clone, Debug, Default)] diff --git a/src/builder/edit_profile.rs b/src/builder/edit_profile.rs index a4b5c996526..2d4df85efbf 100644 --- a/src/builder/edit_profile.rs +++ b/src/builder/edit_profile.rs @@ -1,9 +1,9 @@ use ::internal::prelude::*; /// A builder to edit the current user's settings, to be used in conjunction -/// with [`Context::edit_profile`]. +/// with [`CurrentUser::edit`]. /// -/// [`Context::edit_profile`]: ../client/struct.Context.html#method.edit_profile +/// [`CurrentUser::edit`]: ../model/struct.CurrentUser.html#method.edit #[derive(Clone, Debug, Default)] pub struct EditProfile(pub JsonMap); diff --git a/src/builder/edit_role.rs b/src/builder/edit_role.rs index f17947a69b4..6be09fed9ec 100644 --- a/src/builder/edit_role.rs +++ b/src/builder/edit_role.rs @@ -2,14 +2,15 @@ use std::default::Default; use ::internal::prelude::*; use ::model::{Permissions, Role, permissions}; -/// A builer to create or edit a [`Role`] for use via a number of model and -/// context methods. +/// A builer to create or edit a [`Role`] for use via a number of model methods. /// /// These are: /// -/// - [`Context::create_role`] -/// - [`Context::edit_role`] +/// - [`PartialGuild::create_role`] /// - [`Guild::create_role`] +/// - [`Guild::edit_role`] +/// - [`GuildId::create_role`] +/// - [`GuildId::edit_role`] /// - [`Role::edit`] /// /// Defaults are provided for each parameter on role creation. @@ -30,9 +31,11 @@ use ::model::{Permissions, Role, permissions}; /// .name("a test role")); /// ``` /// -/// [`Context::create_role`]: ../client/struct.Context.html#method.create_role -/// [`Context::edit_role`]: ../client/struct.Context.html#method.edit_role +/// [`PartialGuild::create_role`]: ../model/struct.PartialGuild.html#method.create_role /// [`Guild::create_role`]: ../model/struct.Guild.html#method.create_role +/// [`Guild::edit_role`]: ../model/struct.Guild.html#method.edit_role +/// [`GuildId::create_role`]: ../model/struct.GuildId.html#method.create_role +/// [`GuildId::edit_role`]: ../model/struct.GuildId.html#method.edit_role /// [`Role`]: ../model/struct.Role.html /// [`Role::edit`]: ../model/struct.Role.html#method.edit #[derive(Clone, Debug)] diff --git a/src/model/channel/embed.rs b/src/model/channel/embed.rs index 0db22ef0167..f46f0d36a96 100644 --- a/src/model/channel/embed.rs +++ b/src/model/channel/embed.rs @@ -68,6 +68,22 @@ impl Embed { /// This should only be useful in conjunction with [`Webhook::execute`]. /// /// [`Webhook::execute`]: struct.Webhook.html + /// + /// # Examples + /// + /// Create an embed: + /// + /// ```rust,no_run + /// use serenity::model::Embed; + /// + /// let embed = Embed::fake(|e| e + /// .title("Embed title") + /// .description("Making a basic embed") + /// .field(|f| f + /// .name("A field") + /// .value("Has some content.") + /// .inline(false))); + /// ``` #[inline] pub fn fake(f: F) -> Value where F: FnOnce(CreateEmbed) -> CreateEmbed { Value::Object(f(CreateEmbed::default()).0) diff --git a/src/model/gateway.rs b/src/model/gateway.rs index 52ec9b031cd..8458bbbe118 100644 --- a/src/model/gateway.rs +++ b/src/model/gateway.rs @@ -39,6 +39,23 @@ impl Game { /// Creates a `Game` struct that appears as a `Playing ` status. /// /// **Note**: Maximum `name` length is 128. + /// + /// # Examples + /// + /// Create a command that sets the current game being played: + /// + /// ```rust,no_run + /// # #[macro_use] extern crate serenity; + /// # + /// use serenity::model::Game; + /// + /// command!(game(ctx, _msg, args) { + /// let name = args.join(" "); + /// ctx.set_game(Game::playing(&name)); + /// }); + /// # + /// # fn main() {} + /// ``` pub fn playing(name: &str) -> Game { Game { kind: GameType::Playing, @@ -50,6 +67,24 @@ impl Game { /// Creates a `Game` struct that appears as a `Streaming ` status. /// /// **Note**: Maximum `name` length is 128. + /// + /// # Examples + /// + /// Create a command that sets the current game and stream: + /// + /// ```rust,no_run + /// # #[macro_use] extern crate serenity; + /// # + /// use serenity::model::Game; + /// + /// // Assumes command has min_args set to 2. + /// command!(stream(ctx, _msg, args, stream: String) { + /// let name = args[1..].join(" "); + /// ctx.set_game(Game::streaming(&name, &stream)); + /// }); + /// # + /// # fn main() {} + /// ``` pub fn streaming(name: &str, url: &str) -> Game { Game { kind: GameType::Streaming, diff --git a/src/model/guild/emoji.rs b/src/model/guild/emoji.rs index f2c7e91b99b..9a8ad3965fb 100644 --- a/src/model/guild/emoji.rs +++ b/src/model/guild/emoji.rs @@ -47,6 +47,28 @@ impl Emoji { /// **Note**: Only user accounts may use this method. /// /// [Manage Emojis]: permissions/constant.MANAGE_EMOJIS.html + /// + /// # Examples + /// + /// Delete a given emoji: + /// + /// ```rust,no_run + /// # use serenity::model::{Emoji, EmojiId}; + /// # + /// # let mut emoji = Emoji { + /// # id: EmojiId(7), + /// # name: String::from("blobface"), + /// # managed: false, + /// # require_colons: false, + /// # roles: vec![], + /// # }; + /// # + /// // assuming emoji has been set already + /// match emoji.delete() { + /// Ok(()) => println!("Emoji deleted."), + /// Err(_) => println!("Could not delete emoji.") + /// } + /// ``` #[cfg(feature="cache")] pub fn delete(&self) -> Result<()> { match self.find_guild_id() { @@ -62,6 +84,26 @@ impl Emoji { /// **Note**: Only user accounts may use this method. /// /// [Manage Emojis]: permissions/constant.MANAGE_EMOJIS.html + /// + /// # Examples + /// + /// Change the name of an emoji: + /// + /// ```rust,no_run + /// # use serenity::model::{Emoji, EmojiId}; + /// # + /// # let mut emoji = Emoji { + /// # id: EmojiId(7), + /// # name: String::from("blobface"), + /// # managed: false, + /// # require_colons: false, + /// # roles: vec![], + /// # }; + /// # + /// // assuming emoji has been set already + /// let _ = emoji.edit("blobuwu"); + /// assert_eq!(emoji.name, "blobuwu"); + /// ``` #[cfg(feature="cache")] pub fn edit(&mut self, name: &str) -> Result<()> { match self.find_guild_id() { @@ -86,6 +128,27 @@ impl Emoji { /// Finds the [`Guild`] that owns the emoji by looking through the Cache. /// /// [`Guild`]: struct.Guild.html + /// + /// # Examples + /// + /// Print the guild id that owns this emoji: + /// + /// ```rust,no_run + /// # use serenity::model::{Emoji, EmojiId}; + /// # + /// # let mut emoji = Emoji { + /// # id: EmojiId(7), + /// # name: String::from("blobface"), + /// # managed: false, + /// # require_colons: false, + /// # roles: vec![], + /// # }; + /// # + /// // assuming emoji has been set already + /// if let Some(guild_id) = emoji.find_guild_id() { + /// println!("{} is owned by {}", emoji.name, guild_id); + /// } + /// ``` #[cfg(feature="cache")] pub fn find_guild_id(&self) -> Option { for guild in CACHE.read().unwrap().guilds.values() { @@ -100,6 +163,25 @@ impl Emoji { } /// Generates a URL to the emoji's image. + /// + /// # Examples + /// + /// Print the direct link to the given emoji: + /// + /// ```rust,no_run + /// # use serenity::model::{Emoji, EmojiId}; + /// # + /// # let mut emoji = Emoji { + /// # id: EmojiId(7), + /// # name: String::from("blobface"), + /// # managed: false, + /// # require_colons: false, + /// # roles: vec![], + /// # }; + /// # + /// // assuming emoji has been set already + /// println!("Direct link to emoji image: {}", emoji.url()); + /// ``` #[inline] pub fn url(&self) -> String { format!(cdn!("/emojis/{}.png"), self.id) diff --git a/src/model/guild/role.rs b/src/model/guild/role.rs index df65e614b70..83836759a31 100644 --- a/src/model/guild/role.rs +++ b/src/model/guild/role.rs @@ -83,22 +83,33 @@ impl Role { /// /// Make a role hoisted: /// - /// ```rust,ignore - /// // assuming a `guild` and `role_id` have been bound + /// ```rust,no_run + /// # use serenity::model::RoleId; + /// # let role = RoleId(7).find().unwrap(); + /// // assuming a `role` has already been bound // - /// guild.edit_role(role_id, |r| r.hoist(true)); + /// role.edit(|r| r.hoist(true)); /// ``` /// /// [`Role`]: struct.Role.html /// [Manage Roles]: permissions/constant.MANAGE_ROLES.html #[cfg(all(feature="builder", feature="cache"))] - pub fn edit_role EditRole>(&self, f: F) -> Result { + pub fn edit EditRole>(&self, f: F) -> Result { match self.find_guild() { Ok(guild_id) => guild_id.edit_role(self.id, f), Err(why) => Err(why), } } + /// Alias of [`edit`] + /// + /// [`edit`]: struct.Role.html#method.edit + #[deprecated(since="0.2.1", note="Please use `edit` instead.")] + #[cfg(all(feature="builder", feature="cache"))] + pub fn edit_role EditRole>(&self, f: F) -> Result { + self.edit(f) + } + /// Searches the cache for the guild that owns the role. /// /// # Errors