diff --git a/README.md b/README.md index d9dee26077..a5647234a5 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ docs. A basic ping-pong bot looks like: -```rust,ignore +```rust use std::env; use serenity::async_trait; diff --git a/src/cache/cache_update.rs b/src/cache/cache_update.rs index 7945649ab7..dab188d644 100644 --- a/src/cache/cache_update.rs +++ b/src/cache/cache_update.rs @@ -5,98 +5,10 @@ use super::Cache; /// This may be implemented on a type and used to update the cache via [`Cache::update`]. /// /// **Info**: You may not access the fields of the cache, as they are public for the crate only. -/// -/// # Examples -/// -/// Creating a custom struct implementation to update the cache with: -/// -/// ```rust,ignore -/// use std::collections::hash_map::Entry; -/// -/// use serde_json::json; -/// use serenity::cache::{Cache, CacheUpdate}; -/// use serenity::model::id::UserId; -/// use serenity::model::user::User; -/// -/// // For example, an update to the user's record in the database was -/// // published to a pubsub channel. -/// struct DatabaseUserUpdate { -/// user_avatar: Option, -/// user_discriminator: u16, -/// user_id: UserId, -/// user_is_bot: bool, -/// user_name: String, -/// } -/// -/// #[serenity::async_trait] -/// impl CacheUpdate for DatabaseUserUpdate { -/// // A copy of the old user's data, if it existed in the cache. -/// type Output = User; -/// -/// async fn update(&mut self, cache: &Cache) -> Option { -/// // If an entry for the user already exists, update its fields. -/// match cache.users.entry(self.user_id) { -/// Entry::Occupied(entry) => { -/// let user = entry.get(); -/// let old_user = user.clone(); -/// -/// user.bot = self.user_is_bot; -/// user.discriminator = self.user_discriminator; -/// user.id = self.user_id; -/// -/// if user.avatar != self.user_avatar { -/// user.avatar = self.user_avatar.clone(); -/// } -/// -/// if user.name != self.user_name { -/// user.name = self.user_name.clone(); -/// } -/// -/// // Return the old copy for the user's sake. -/// Some(old_user) -/// }, -/// Entry::Vacant(entry) => { -/// // We can convert a [`Value`] to a User for test -/// // purposes. -/// let user = from_value::(json!({ -/// "id": self.user_id, -/// "avatar": self.user_avatar.clone(), -/// "bot": self.user_is_bot, -/// "discriminator": self.user_discriminator, -/// "username": self.user_name.clone(), -/// })).expect("Error making user"); -/// -/// entry.insert(user); -/// -/// // There was no old copy, so return None. -/// None -/// }, -/// } -/// } -/// } -/// -/// # async fn run() { -/// // Create an instance of the cache. -/// let mut cache = Cache::new(); -/// -/// // This is a sample pubsub message that you might receive from your -/// // database. -/// let mut update_message = DatabaseUserUpdate { -/// user_avatar: None, -/// user_discriminator: 6082, -/// user_id: UserId::new(379740138303127564), -/// user_is_bot: true, -/// user_name: "TofuBot".to_owned(), -/// }; -/// -/// // Update the cache with the message. -/// cache.update(&mut update_message).await; -/// # } -/// ``` pub trait CacheUpdate { /// The return type of an update. /// - /// If there is nothing to return, specify this type as an unit (`()`). + /// If there is nothing to return, specify this type to be the unit `()`. type Output; /// Updates the cache with the implementation. diff --git a/src/gateway/sharding/shard_messenger.rs b/src/gateway/sharding/shard_messenger.rs index 39bb10fb82..2f4caeef40 100644 --- a/src/gateway/sharding/shard_messenger.rs +++ b/src/gateway/sharding/shard_messenger.rs @@ -136,9 +136,9 @@ impl ShardMessenger { /// /// Set the current user as playing `"Heroes of the Storm"` and being online: /// - /// ```rust,ignore + /// ```rust,no_run /// # use serenity::gateway::Shard; - /// # async fn run(shard: Shard) -> Result<(), Box> { + /// # async fn run(mut shard: Shard) -> Result<(), Box> { /// use serenity::gateway::ActivityData; /// use serenity::model::user::OnlineStatus; /// diff --git a/src/model/channel/guild_channel.rs b/src/model/channel/guild_channel.rs index f11b96f11a..7f8a5d1b57 100644 --- a/src/model/channel/guild_channel.rs +++ b/src/model/channel/guild_channel.rs @@ -224,9 +224,18 @@ impl GuildChannel { /// /// Create an invite that can only be used 5 times: /// - /// ```rust,ignore - /// let builder = CreateBuilder::default().max_uses(5); - /// let invite = channel.create_invite(&context, builder).await; + /// ```rust,no_run + /// # use serenity::builder::CreateInvite; + /// # use serenity::http::Http; + /// # use serenity::model::channel::GuildChannel; + /// # async fn run() -> Result<(), Box> { + /// # let channel: GuildChannel = unimplemented!(); + /// # let http: Http = unimplemented!(); + /// + /// let builder = CreateInvite::new().max_uses(5); + /// let invite = channel.create_invite(&http, builder).await; + /// # Ok(()) + /// # } /// ``` /// /// # Errors diff --git a/src/model/guild/member.rs b/src/model/guild/member.rs index 6ef2f6144a..9982e1bb4a 100644 --- a/src/model/guild/member.rs +++ b/src/model/guild/member.rs @@ -259,17 +259,18 @@ impl Member { /// /// # Examples /// - /// Kick a member from its guild: - /// - /// ```rust,ignore + /// Kick a member from the guild: + /// + /// ```rust,no_run + /// # use serenity::http::Http; + /// # use serenity::model::guild::Member; + /// # async fn run() -> Result<(), Box> { + /// # let http: Http = unimplemented!(); + /// # let member: Member = unimplemented!(); /// // assuming a `member` has already been bound - /// match member.kick(None).await { - /// Ok(()) => println!("Successfully kicked member"), - /// Err(Error::Model(ModelError::GuildNotFound)) => { - /// println!("Couldn't determine guild of member"); - /// }, - /// _ => {}, - /// } + /// member.kick(&http, None).await?; + /// # Ok(()) + /// # } /// ``` /// /// # Errors @@ -314,14 +315,6 @@ impl Member { /// Returns the guild-level permissions for the member. /// - /// # Examples - /// - /// ```rust,ignore - /// // assuming there's a `member` variable gotten from anything. - /// println!("The permission bits for the member are: {}", - /// member.permissions(&cache).expect("permissions").bits()); - /// ``` - /// /// # Errors /// /// Returns a [`ModelError::GuildNotFound`] if the guild the member's in could not be @@ -430,13 +423,6 @@ impl Member { impl fmt::Display for Member { /// Mentions the user so that they receive a notification. /// - /// # Examples - /// - /// ```rust,ignore - /// // assumes a `member` has already been bound - /// println!("{} is a member!", member); - /// ``` - /// /// This is in the format of `<@USER_ID>`. fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { fmt::Display::fmt(&self.user.mention(), f) diff --git a/src/model/guild/mod.rs b/src/model/guild/mod.rs index 225c963e21..0e672956e6 100644 --- a/src/model/guild/mod.rs +++ b/src/model/guild/mod.rs @@ -401,9 +401,18 @@ impl Guild { /// /// Ban a member and remove all messages they've sent in the last 4 days: /// - /// ```rust,ignore - /// // assumes a `user` and `guild` have already been bound - /// let _ = guild.ban(user, 4, None); + /// ```rust,no_run + /// # use serenity::http::Http; + /// # use serenity::model::guild::Guild; + /// # use serenity::model::id::UserId; + /// # async fn run() -> Result<(), Box> { + /// # let http: Http = unimplemented!(); + /// # let guild: Guild = unimplemented!(); + /// # let user_id: UserId = unimplemented!(); + /// // assumes a `user_id` and `guild` have already been bound + /// guild.ban(&http, user_id, 4, None).await?; + /// # Ok(()) + /// # } /// ``` /// /// # Errors @@ -524,10 +533,14 @@ impl Guild { /// /// Create a guild called `"test"` in the [US West region] with no icon: /// - /// ```rust,ignore - /// use serenity::model::Guild; - /// - /// let _guild = Guild::create_guild(&http, "test", None).await; + /// ```rust,no_run + /// # use serenity::http::Http; + /// use serenity::model::guild::Guild; + /// # async fn run() -> Result<(), Box> { + /// # let http: Http = unimplemented!(); + /// let guild = Guild::create(&http, "test", None).await; + /// # Ok(()) + /// # } /// ``` /// /// # Errors diff --git a/src/model/guild/partial_guild.rs b/src/model/guild/partial_guild.rs index 2dcd8e422d..e417d6954a 100644 --- a/src/model/guild/partial_guild.rs +++ b/src/model/guild/partial_guild.rs @@ -270,9 +270,18 @@ impl PartialGuild { /// /// Ban a member and remove all messages they've sent in the last 4 days: /// - /// ```rust,ignore - /// // assumes a `user` and `guild` have already been bound - /// let _ = guild.ban(user, 4); + /// ```rust,no_run + /// # use serenity::http::Http; + /// # use serenity::model::guild::PartialGuild; + /// # use serenity::model::id::UserId; + /// # async fn run() -> Result<(), Box> { + /// # let http: Http = unimplemented!(); + /// # let guild: PartialGuild = unimplemented!(); + /// # let user_id: UserId = unimplemented!(); + /// // assumes a `user_id` and `guild` have already been bound + /// guild.ban(&http, user_id, 4, None).await?; + /// # Ok(()) + /// # } /// ``` /// /// # Errors diff --git a/src/model/user.rs b/src/model/user.rs index a226b6018f..542f398f91 100644 --- a/src/model/user.rs +++ b/src/model/user.rs @@ -27,6 +27,8 @@ use crate::model::utils::avatar_url; /// ```rust,ignore /// use std::num::NonZeroU16; /// +/// use serde::{Deserialize, Serialize}; +/// /// #[derive(Deserialize, Serialize)] /// struct A { /// #[serde(with = "discriminator")] @@ -458,15 +460,6 @@ impl User { /// Check if a user has a [`Role`]. This will retrieve the [`Guild`] from the [`Cache`] if it /// is available, and then check if that guild has the given [`Role`]. /// - /// # Examples - /// - /// Check if a guild has a [`Role`] by Id: - /// - /// ```rust,ignore - /// // Assumes a 'guild_id' and `role_id` have already been bound - /// let _ = message.author.has_role(guild_id, role_id); - /// ``` - /// /// [`Cache`]: crate::cache::Cache /// /// # Errors diff --git a/src/model/webhook.rs b/src/model/webhook.rs index 49f6179ea2..5a2392188f 100644 --- a/src/model/webhook.rs +++ b/src/model/webhook.rs @@ -470,10 +470,6 @@ impl Webhook { /// Returns the url of the webhook. /// - /// ```rust,ignore - /// assert_eq!(hook.url(), "https://discord.com/api/webhooks/245037420704169985/ig5AO-wdVWpCBtUUMxmgsWryqgsW3DChbKYOINftJ4DCrUbnkedoYZD0VOH1QLr-S3sV") - /// ``` - /// /// # Errors /// /// Returns an [`Error::Model`] if the [`Self::token`] is [`None`]. diff --git a/src/utils/message_builder.rs b/src/utils/message_builder.rs index 797c40dbd2..a5975a8c8f 100644 --- a/src/utils/message_builder.rs +++ b/src/utils/message_builder.rs @@ -183,7 +183,7 @@ impl MessageBuilder { /// /// Pushing a Rust codeblock: /// - /// ```rust,ignore + /// ```rust,no_run /// use serenity::utils::MessageBuilder; /// /// let code = r#"