Make Guild::shard_id follow additive features (#2813)

This PR:
- Removes the `cache` feature locked function that called shard_count
for the user, since that is useless and breaks the "all features should
be additive" guidance
- Removes the useless example that just showed how to call a function
- Removed duplicate documentation on Guild, PartialGuild, and
InviteGuild just to direct to the canonical documentation where the
function is implemented.

src/cache/event.rs

@@ -464,7 +464,7 @@ impl CacheUpdate for ReadyEvent {
         for guild_entry in cache.guilds.iter() {
             let guild = guild_entry.key();
             // Only handle data for our shard.
-            if crate::utils::shard_id(*guild, shard_data.total.get()) == shard_data.id.0
+            if crate::utils::shard_id(*guild, shard_data.total) == shard_data.id.0
                 && !ready_guilds_hashset.contains(guild)
             {
                 guilds_to_remove.push(*guild);

src/model/guild/guild_id.rs

@@ -1210,40 +1210,13 @@ impl GuildId {
 
     /// Returns the Id of the shard associated with the guild.
     ///
-    /// When the cache is enabled this will automatically retrieve the total number of shards.
-    ///
-    /// **Note**: When the cache is enabled, this function unlocks the cache to retrieve the total
-    /// number of shards in use. If you already have the total, consider using [`utils::shard_id`].
+    /// This is just a shortcut for [`utils::shard_id`], the shard count should
+    /// be fetched using [`Cache::shard_count`] if possible.
     ///
     /// [`utils::shard_id`]: crate::utils::shard_id
-    #[cfg(all(feature = "cache", feature = "utils"))]
-    #[must_use]
-    pub fn shard_id(self, cache: &Cache) -> u16 {
-        crate::utils::shard_id(self, cache.shard_count().get())
-    }
-
-    /// Returns the Id of the shard associated with the guild.
-    ///
-    /// When the cache is enabled this will automatically retrieve the total number of shards.
-    ///
-    /// When the cache is not enabled, the total number of shards being used will need to be
-    /// passed.
-    ///
-    /// # Examples
-    ///
-    /// Retrieve the Id of the shard for a guild with Id `81384788765712384`, using 17 shards:
-    ///
-    /// ```rust
-    /// use serenity::model::id::GuildId;
-    /// use serenity::utils;
-    ///
-    /// let guild_id = GuildId::new(81384788765712384);
-    ///
-    /// assert_eq!(guild_id.shard_id(17), 7);
-    /// ```
-    #[cfg(all(feature = "utils", not(feature = "cache")))]
     #[must_use]
-    pub fn shard_id(self, shard_count: u16) -> u16 {
+    #[cfg(feature = "utils")]
+    pub fn shard_id(self, shard_count: std::num::NonZeroU16) -> u16 {
         crate::utils::shard_id(self, shard_count)
     }
 

src/model/guild/mod.rs

@@ -2033,39 +2033,11 @@ impl Guild {
 
     /// Returns the Id of the shard associated with the guild.
     ///
-    /// When the cache is enabled this will automatically retrieve the total number of shards.
-    ///
-    /// **Note**: When the cache is enabled, this function unlocks the cache to retrieve the total
-    /// number of shards in use. If you already have the total, consider using [`utils::shard_id`].
-    ///
-    /// [`utils::shard_id`]: crate::utils::shard_id
-    #[cfg(all(feature = "cache", feature = "utils"))]
-    pub fn shard_id(&self, cache: &Cache) -> u16 {
-        self.id.shard_id(cache)
-    }
-
-    /// Returns the Id of the shard associated with the guild.
-    ///
-    /// When the cache is enabled this will automatically retrieve the total number of shards.
-    ///
-    /// When the cache is not enabled, the total number of shards being used will need to be
-    /// passed.
-    ///
-    /// # Examples
-    ///
-    /// Retrieve the Id of the shard for a guild with Id `81384788765712384`, using 17 shards:
-    ///
-    /// ```rust,ignore
-    /// use serenity::utils;
-    ///
-    /// // assumes a `guild` has already been bound
-    ///
-    /// assert_eq!(guild.shard_id(17), 7);
-    /// ```
-    #[cfg(all(feature = "utils", not(feature = "cache")))]
+    /// See the documentation for [`GuildId::shard_id`].
     #[must_use]
-    pub fn shard_id(&self, shard_count: u16) -> u16 {
-        self.id.shard_id(shard_count)
+    #[cfg(feature = "utils")]
+    pub fn shard_id(&self, shard_total: std::num::NonZeroU16) -> u16 {
+        self.id.shard_id(shard_total)
     }
 
     /// Returns the formatted URL of the guild's splash image, if one exists.

src/model/guild/partial_guild.rs

@@ -1205,40 +1205,11 @@ impl PartialGuild {
 
     /// Returns the Id of the shard associated with the guild.
     ///
-    /// When the cache is enabled this will automatically retrieve the total number of shards.
-    ///
-    /// **Note**: When the cache is enabled, this function unlocks the cache to retrieve the total
-    /// number of shards in use. If you already have the total, consider using [`utils::shard_id`].
-    ///
-    /// [`utils::shard_id`]: crate::utils::shard_id
-    #[cfg(all(feature = "cache", feature = "utils"))]
-    #[must_use]
-    pub fn shard_id(&self, cache: &Cache) -> u16 {
-        self.id.shard_id(cache)
-    }
-
-    /// Returns the Id of the shard associated with the guild.
-    ///
-    /// When the cache is enabled this will automatically retrieve the total number of shards.
-    ///
-    /// When the cache is not enabled, the total number of shards being used will need to be
-    /// passed.
-    ///
-    /// # Examples
-    ///
-    /// Retrieve the Id of the shard for a guild with Id `81384788765712384`, using 17 shards:
-    ///
-    /// ```rust,ignore
-    /// use serenity::utils;
-    ///
-    /// // assumes a `guild` has already been bound
-    ///
-    /// assert_eq!(guild.shard_id(17), 7);
-    /// ```
-    #[cfg(all(feature = "utils", not(feature = "cache")))]
+    /// See the documentation for [`GuildId::shard_id`].
     #[must_use]
-    pub fn shard_id(&self, shard_count: u16) -> u16 {
-        self.id.shard_id(shard_count)
+    #[cfg(feature = "utils")]
+    pub fn shard_id(&self, shard_total: std::num::NonZeroU16) -> u16 {
+        self.id.shard_id(shard_total)
     }
 
     /// Returns the formatted URL of the guild's splash image, if one exists.

src/model/invite.rs

@@ -5,8 +5,6 @@ use nonmax::NonMaxU64;
 use super::prelude::*;
 #[cfg(feature = "model")]
 use crate::builder::CreateInvite;
-#[cfg(all(feature = "cache", feature = "model"))]
-use crate::cache::Cache;
 #[cfg(feature = "model")]
 use crate::http::{CacheHttp, Http};
 use crate::internal::prelude::*;
@@ -228,40 +226,11 @@ pub struct InviteGuild {
 impl InviteGuild {
     /// Returns the Id of the shard associated with the guild.
     ///
-    /// When the cache is enabled this will automatically retrieve the total number of shards.
-    ///
-    /// **Note**: When the cache is enabled, this function unlocks the cache to retrieve the total
-    /// number of shards in use. If you already have the total, consider using [`utils::shard_id`].
-    ///
-    /// [`utils::shard_id`]: crate::utils::shard_id
-    #[cfg(all(feature = "cache", feature = "utils"))]
-    #[must_use]
-    pub fn shard_id(&self, cache: &Cache) -> u16 {
-        self.id.shard_id(cache)
-    }
-
-    /// Returns the Id of the shard associated with the guild.
-    ///
-    /// When the cache is enabled this will automatically retrieve the total number of shards.
-    ///
-    /// When the cache is not enabled, the total number of shards being used will need to be
-    /// passed.
-    ///
-    /// # Examples
-    ///
-    /// Retrieve the Id of the shard for a guild with Id `81384788765712384`, using 17 shards:
-    ///
-    /// ```rust,ignore
-    /// use serenity::utils;
-    ///
-    /// // assumes a `guild` has already been bound
-    ///
-    /// assert_eq!(guild.shard_id(17), 7);
-    /// ```
-    #[cfg(all(feature = "utils", not(feature = "cache")))]
+    /// See the documentation for [`GuildId::shard_id`].
     #[must_use]
-    pub fn shard_id(&self, shard_count: u16) -> u16 {
-        self.id.shard_id(shard_count)
+    #[cfg(feature = "utils")]
+    pub fn shard_id(&self, shard_total: std::num::NonZeroU16) -> u16 {
+        self.id.shard_id(shard_total)
     }
 }
 

src/utils/mod.rs

@@ -478,11 +478,13 @@ pub(crate) fn user_perms(
 /// use serenity::model::id::GuildId;
 /// use serenity::utils;
 ///
-/// assert_eq!(utils::shard_id(GuildId::new(81384788765712384), 17), 7);
+/// let guild_id = GuildId::new(81384788765712384);
+/// let shard_total = std::num::NonZeroU16::new(17).unwrap();
+///
+/// assert_eq!(utils::shard_id(guild_id, shard_total), 7);
 /// ```
 #[must_use]
-pub fn shard_id(guild_id: GuildId, shard_count: u16) -> u16 {
-    let shard_count = check_shard_total(shard_count);
+pub fn shard_id(guild_id: GuildId, shard_count: NonZeroU16) -> u16 {
     ((guild_id.get() >> 22) % u64::from(shard_count.get())) as u16
 }