Fix docs

Author: mkrasnitski

serenity-core/src/cache/mod.rs

@@ -1,4 +1,4 @@
-//! A cache containing data received from [`Shard`]s.
+//! A cache containing data received from the API.
 //!
 //! Using the cache allows to avoid REST API requests via the [`http`] module where possible.
 //! Issuing too many requests will lead to ratelimits.
@@ -20,7 +20,6 @@
 //! is "definitely no". If you do not care about RAM and want your bot to be able to access data
 //! while needing to hit the REST API as little as possible, then the answer is "yes".
 //!
-//! [`Shard`]: crate::gateway::Shard
 //! [`http`]: crate::http
 //! [Manage Guild]: Permissions::MANAGE_GUILD
 
@@ -125,7 +124,7 @@ struct CachedShardData {
     has_sent_shards_ready: bool,
 }
 
-/// A cache containing data received from [`Shard`]s.
+/// A cache containing data received from the API.
 ///
 /// Using the cache allows to avoid REST API requests via the [`http`] module where possible.
 /// Issuing too many requests will lead to ratelimits.
@@ -141,7 +140,6 @@ struct CachedShardData {
 ///
 /// The documentation of each event contains the required gateway intents.
 ///
-/// [`Shard`]: crate::gateway::Shard
 /// [`http`]: crate::http
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
 #[derive(Debug)]
@@ -268,10 +266,8 @@ impl Cache {
     /// data received. A single [`User`] may have multiple associated member objects that have not
     /// been received.
     ///
-    /// This can be used in combination with [`Shard::chunk_guild`], and can be used to determine
-    /// how many members have not yet been received.
-    ///
-    /// [`Shard::chunk_guild`]: crate::gateway::Shard::chunk_guild
+    /// This can be used in combination with guild chunking, and can be used to determine how many
+    /// members have not yet been received.
     pub fn unknown_members(&self) -> u64 {
         let mut total = 0;
 
@@ -290,9 +286,9 @@ impl Cache {
 
     /// Fetches a vector of all [`Guild`]s' Ids that are stored in the cache.
     ///
-    /// Note that if you are utilizing multiple [`Shard`]s, then the guilds retrieved over all
-    /// shards are included in this count -- not just the current [`Context`]'s shard, if accessing
-    /// from one.
+    /// Note that if you are utilizing multiple shards, then the guilds retrieved over all shards
+    /// are included in this count -- not just the current shard (assuming you are connecting via
+    /// the gateway).
     ///
     /// # Examples
     ///
@@ -319,9 +315,6 @@ impl Cache {
     ///     }
     /// }
     /// ```
-    ///
-    /// [`Context`]: crate::gateway::client::Context
-    /// [`Shard`]: crate::gateway::Shard
     pub fn guilds(&self) -> Vec<GuildId> {
         let unavailable_guilds = self.unavailable_guilds();
 

serenity-core/src/http/client.rs

@@ -521,9 +521,7 @@ impl Http {
 
     /// Creates an application emoji with the given data.
     ///
-    /// See [`Context::create_application_emoji`] for required fields.
-    ///
-    /// [`Context::create_application_emoji`]: crate::gateway::client::Context::create_application_emoji
+    /// See [`GuildId::create_emoji`] for required fields.
     pub async fn create_application_emoji(&self, map: &impl serde::Serialize) -> Result<Emoji> {
         self.fire(Request {
             body: Some(to_vec(map)?),
@@ -627,10 +625,8 @@ impl Http {
 
     /// Creates a guild with the data provided.
     ///
-    /// Only a [`PartialGuild`] will be immediately returned, and a full [`Guild`] will be received
-    /// over a [`Shard`], if at least one is running.
-    ///
-    /// [`Shard`]: crate::gateway::Shard
+    /// Only a [`PartialGuild`] will be immediately returned, and a full [`Guild`] will later be
+    /// sent over the gateway via a [`GuildCreateEvent`], if at least one shard is running.
     #[deprecated = "This endpoint has been deprecated by Discord and will stop functioning after July 15, 2025. For more information, see: https://discord.com/developers/docs/change-log#deprecating-guild-creation-by-apps"]
     pub async fn create_guild(&self, map: &impl serde::Serialize) -> Result<PartialGuild> {
         self.fire(Request {
@@ -1485,9 +1481,7 @@ impl Http {
 
     /// Changes application emoji information.
     ///
-    /// See [`Context::edit_application_emoji`] for required fields.
-    ///
-    /// [`Context::edit_application_emoji`]: crate::gateway::client::Context::edit_application_emoji
+    /// See [`GuildId::edit_emoji`] for required fields.
     pub async fn edit_application_emoji(
         &self,
         emoji_id: EmojiId,

serenity-core/src/http/mod.rs

@@ -5,18 +5,14 @@
 //! implements protection to pre-emptively ratelimit, to ensure that no wasted requests are made.
 //!
 //! The HTTP module comprises of two types of requests:
-//! - REST API requests, which require an authorization token;
+//! - REST API requests, which require authenticating to Discord's gateway using a token;
 //! - Other requests, which do not require an authorization token.
 //!
-//! The former require a [`Client`] to have logged in, while the latter may be made regardless of
-//! any other usage of the library.
-//!
 //! If a request spuriously fails, it will be retried once.
 //!
 //! Note that you may want to perform requests through a [model]s' instance methods where possible,
 //! as they each offer different levels of a high-level interface to the HTTP module.
 //!
-//! [`Client`]: crate::Client
 //! [model]: crate::model
 
 mod client;

serenity-core/src/model/application/command.rs

@@ -91,7 +91,7 @@ pub struct Command {
 impl Command {
     /// Create a global [`Command`], overriding an existing one with the same name if it exists.
     ///
-    /// When a created [`Command`] is used, the [`InteractionCreate`] event will be emitted.
+    /// When a created [`Command`] is used, a [`InteractionCreateEvent`] will be emitted.
     ///
     /// **Note**: Global commands may take up to an hour to be updated in the user slash commands
     /// list. If an outdated command data is sent by a user, discord will consider it as an error
@@ -142,8 +142,6 @@ impl Command {
     /// # Errors
     ///
     /// See [`CreateCommand::execute`] for a list of possible errors.
-    ///
-    /// [`InteractionCreate`]: crate::gateway::client::FullEvent::InteractionCreate
     pub async fn create_global_command(http: &Http, builder: CreateCommand<'_>) -> Result<Command> {
         builder.execute(http, None).await
     }

serenity-core/src/model/error.rs

@@ -97,7 +97,7 @@ impl fmt::Display for Minimum {
 ///
 /// This is always wrapped within the library's [`Error::Model`] variant.
 ///
-/// [`Error::Model`]: crate::Error::Model
+/// [`Error::Model`]: crate::error::Error::Model
 /// [`model`]: crate::model
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 #[non_exhaustive]

serenity-core/src/model/event.rs

@@ -272,14 +272,13 @@ pub struct GuildMembersChunkEvent {
     pub chunk_index: u32,
     /// Total number of expected chunks for this response.
     pub chunk_count: u32,
-    /// When passing an invalid ID to [`crate::gateway::ShardRunnerMessage::ChunkGuild`], it will
-    /// be returned here.
+    /// Any invalid IDs passed when requesting guild chunking will be returned here.
     #[serde(default)]
     pub not_found: FixedArray<GenericId>,
-    /// When passing true to [`crate::gateway::ShardRunnerMessage::ChunkGuild`], presences of the
-    /// returned members will be here.
+    /// If the `presences` field is set when requesting guild chunking, this field will be filled
+    /// with member presences.
     pub presences: Option<Vec<Presence>>,
-    /// Nonce used in the [`crate::gateway::ShardRunnerMessage::ChunkGuild`] request.
+    /// Nonce used in the guild chunking request.
     pub nonce: Option<FixedString>,
 }
 

serenity-core/src/model/guild/mod.rs

@@ -34,8 +34,6 @@ pub use self::system_channel::*;
 pub use self::welcome_screen::*;
 #[cfg(feature = "model")]
 use crate::builder::EditGuild;
-#[cfg(doc)]
-use crate::constants::LARGE_THRESHOLD;
 #[cfg(feature = "model")]
 use crate::http::{CacheHttp, Http};
 use crate::model::prelude::*;
@@ -210,7 +208,10 @@ pub struct Guild {
     /// Users who are members of the guild.
     ///
     /// Members might not all be available when the [`ReadyEvent`] is received if the
-    /// [`Self::member_count`] is greater than the [`LARGE_THRESHOLD`] set by the library.
+    /// [`Self::member_count`] is greater than the [Large Threshold] set by the library when
+    /// identifying.
+    ///
+    /// [Large Threshold]: https://discord.com/developers/docs/events/gateway-events#identify-identify-structure
     pub members: ExtractMap<UserId, Member>,
     /// All voice and text channels contained within a guild.
     ///
@@ -285,8 +286,8 @@ impl Guild {
 
     /// Creates a guild with the data provided.
     ///
-    /// Only a [`PartialGuild`] will be immediately returned, and a full [`Guild`] will be received
-    /// over a [`Shard`].
+    /// Only a [`PartialGuild`] will be immediately returned, and a full [`Guild`] will later be
+    /// sent over the gateway via a [`GuildCreateEvent`], if at least one shard is running.
     ///
     /// **Note**: This endpoint is usually only available for user accounts. Refer to Discord's
     /// information for the endpoint [here][whitelist] for more information. If you require this as
@@ -310,7 +311,6 @@ impl Guild {
     ///
     /// Returns [`Error::Http`] if the current user cannot create a Guild.
     ///
-    /// [`Shard`]: crate::gateway::Shard
     /// [whitelist]: https://discord.com/developers/docs/resources/guild#create-guild
     #[deprecated = "This endpoint has been deprecated by Discord and will stop functioning after July 15, 2025. For more information, see: https://discord.com/developers/docs/change-log#deprecating-guild-creation-by-apps"]
     pub async fn create(http: &Http, name: &str, icon: Option<ImageHash>) -> Result<PartialGuild> {

serenity-core/src/utils/custom_message.rs

@@ -2,10 +2,8 @@ use crate::model::prelude::*;
 
 /// A builder for constructing a personal [`Message`] instance.
 ///
-/// This can be useful for emitting a manual [`dispatch`] to the framework, but you don't have a
+/// This can be useful for emitting a manual dispatch to the framework, but you don't have a
 /// message in hand, or just have a fragment of its data.
-///
-/// [`dispatch`]: crate::framework::Framework::dispatch
 #[derive(Clone, Default, Debug)]
 pub struct CustomMessage {
     msg: Message,

src/gateway/client/mod.rs

@@ -472,6 +472,7 @@ impl Client {
     /// manager.
     ///
     /// [gateway docs]: crate::gateway#sharding
+    /// [`Error::Http`]: serenity_core::error::Error::Http
     #[cfg_attr(feature = "tracing_instrument", instrument(skip(self)))]
     pub async fn start(&mut self) -> Result<()> {
         self.start_connection(0, 0, NonZeroU16::MIN).await
@@ -515,6 +516,7 @@ impl Client {
     /// manager.
     ///
     /// [gateway docs]: crate::gateway#sharding
+    /// [`Error::Http`]: serenity_core::error::Error::Http
     #[cfg_attr(feature = "tracing_instrument", instrument(skip(self)))]
     pub async fn start_autosharded(&mut self) -> Result<()> {
         let (end, total) = {
@@ -581,6 +583,7 @@ impl Client {
     /// manager.
     ///
     /// [gateway docs]: crate::gateway#sharding
+    /// [`Error::Http`]: serenity_core::error::Error::Http
     #[cfg_attr(feature = "tracing_instrument", instrument(skip(self)))]
     pub async fn start_shard(&mut self, shard: u16, shards: u16) -> Result<()> {
         self.start_connection(shard, shard, check_shard_total(shards)).await
@@ -624,6 +627,7 @@ impl Client {
     /// manager.
     ///
     /// [Gateway docs]: crate::gateway#sharding
+    /// [`Error::Http`]: serenity_core::error::Error::Http
     #[cfg_attr(feature = "tracing_instrument", instrument(skip(self)))]
     pub async fn start_shards(&mut self, total_shards: u16) -> Result<()> {
         self.start_connection(0, total_shards - 1, check_shard_total(total_shards)).await
@@ -667,6 +671,7 @@ impl Client {
     /// manager.
     ///
     /// [Gateway docs]: crate::gateway#sharding
+    /// [`Error::Http`]: serenity_core::error::Error::Http
     #[cfg_attr(feature = "tracing_instrument", instrument(skip(self)))]
     pub async fn start_shard_range(&mut self, range: Range<u16>, total_shards: u16) -> Result<()> {
         self.start_connection(range.start, range.end, check_shard_total(total_shards)).await