Improve some docs (#3027)

Improved wording and removed some sentences that are no longer relevant.
These docs are mostly the ones that were touched by #2988.

Author: mkrasnitski

src/gateway/client/context.rs

@@ -7,11 +7,11 @@ use crate::gateway::{ActivityData, ShardMessenger, ShardRunner};
 use crate::http::Http;
 use crate::model::prelude::*;
 
-/// The context is a general utility struct provided on event dispatches.
+/// A general utility struct provided on event dispatches.
 ///
-/// The Context helps with dealing with the current "context" of the event dispatch. The context
-/// also acts as a general high-level interface over the associated [`Shard`] which received
-/// the event, or the low-level [`http`] module.
+/// The [`Context`] helps with dealing with the current "context" of the event dispatch. It also
+/// acts as a general high-level interface over the low-level [`http`] module, plus the associated
+/// [`Shard`] which received the event.
 ///
 /// The context contains "shortcuts", like for interacting with the shard. Methods like
 /// [`Self::set_activity`] will unlock the shard and perform an update for you to save a bit of

src/gateway/client/event_handler.rs

@@ -30,9 +30,10 @@ macro_rules! event_handler {
                 }
             )*
 
-            /// Checks if the `event` should be dispatched (`true`) or ignored (`false`).
+            /// Checks if the `event` should be dispatched or ignored. Returns `true` by default.
             ///
-            /// This affects [`crate::collector::collect`], [`crate::framework::Framework::dispatch`] and this `EventHandler` trait.
+            /// Returning `false` will drop an event and prevent it being dispatched by any
+            /// frameworks and will exclude it from any collectors.
             ///
             /// ## Warning
             ///
@@ -508,10 +509,10 @@ pub trait RawEventHandler: Send + Sync {
     /// Dispatched when any event occurs
     async fn raw_event(&self, _ctx: Context, _ev: &Event) {}
 
-    /// Checks if the `event` should be dispatched (`true`) or ignored (`false`).
+    /// Checks if the `event` should be dispatched or ignored. Returns `true` by default.
     ///
-    /// This affects [`crate::collector::collect`], [`crate::framework::Framework::dispatch`] and
-    /// this `EventHandler` trait.
+    /// Returning `false` will drop an event and prevent it being dispatched by any frameworks and
+    /// will exclude it from any collectors.
     ///
     /// ## Warning
     ///

src/gateway/client/mod.rs

@@ -343,11 +343,11 @@ impl IntoFuture for ClientBuilder {
     }
 }
 
-/// A wrapper for HTTP and gateway connections.
+/// A high-level client that abstracts over the REST API as well as Discord's gateway.
 ///
-/// The Client is the way to be able to start sending authenticated requests over the REST API, as
-/// well as initializing a WebSocket connection through [`Shard`]s. Refer to the [documentation on
-/// using sharding][super::sharding] for more information.
+/// It enables the user to start sending authenticated HTTP requests, plus also initialize a
+/// WebSocket connection to the gateway through [`Shard`]s. Refer to the [documentation on using
+/// sharding][super::sharding] for more information.
 ///
 /// # Event Handlers
 ///

src/gateway/sharding/mod.rs

@@ -1,4 +1,4 @@
-//! Module containing types for gateway sharding.
+//! Mechanisms for configuring and managing sharded gateway connections.
 //!
 //! Sharding is a method for load-balancing bots across separate threads or processes. Sharding is
 //! enforced on bots by Discord once they reach a certain number of guilds (2500). Once this
@@ -62,34 +62,31 @@ use crate::model::gateway::{GatewayIntents, ShardInfo};
 use crate::model::id::{ApplicationId, GuildId, ShardId};
 use crate::model::user::OnlineStatus;
 
-/// A Shard is a higher-level handler for a websocket connection to Discord's gateway.
+/// An abstract handler for a websocket connection to Discord's gateway.
 ///
-/// The shard allows for sending and receiving messages over the websocket,
-/// such as setting the active activity, reconnecting, syncing guilds, and more.
+/// Allows a user to send and receive messages over said websocket, including:
+///   * setting the current activity
+///   * setting the current online status
+///   * receiving gateway events
+///   * connection management via heartbeating
 ///
-/// Refer to the [module-level documentation][module docs] for information on effectively using
-/// multiple shards, if you need to.
-///
-/// Note that there are additional methods available if you are manually managing a shard yourself,
-/// although they are hidden from the documentation since there are few use cases for doing so.
+/// Shard management (including starting, restarting, heartbeating), is performed by the [`Client`]
+/// automatically on the user's behalf.
 ///
 /// # Stand-alone shards
 ///
 /// You may instantiate a shard yourself - decoupled from the [`Client`] - by calling
 /// [`Shard::new`]. Most use cases will not necessitate this, and unless you're doing something
 /// really weird you can just let the client do it for you.
 ///
-/// **Note**: You _really_ do not need to do this. Just call one of the appropriate methods on the
-/// [`Client`].
+/// **Note**: You _really_ do not need to do this, especially if using multiple shards. Just call
+/// one of the appropriate methods on the [`Client`].
 ///
 /// # Examples
 ///
 /// See the documentation for [`Self::new`] on how to use this.
 ///
 /// [`Client`]: crate::Client
-/// [`receive`]: #method.receive
-/// [docs]: https://discord.com/developers/docs/topics/gateway#sharding
-/// [module docs]: crate::gateway#sharding
 pub struct Shard {
     pub client: WsClient,
     presence: PresenceData,

src/http/client.rs

@@ -59,7 +59,7 @@ where
     }
 }
 
-/// A builder for the underlying [`Http`] client that performs requests to Discord's HTTP API
+/// A builder for the underlying [`Http`] client.
 ///
 /// If you do not need to use a proxy or do not need to disable the rate limiter, you can use
 /// [`Http::new`] instead.
@@ -232,6 +232,8 @@ fn reason_into_header(reason: &str) -> Headers {
     headers
 }
 
+/// A low-level client for sending requests to Discord's HTTP REST API.
+///
 /// **Note**: For all member functions that return a [`Result`], the Error kind will be either
 /// [`Error::Http`] or [`Error::Json`].
 #[derive(Debug)]

src/model/guild/member.rs

@@ -559,8 +559,10 @@ pub struct PartialThreadMember {
 
 /// A model representing a user in a Guild Thread.
 ///
-/// [Discord docs](https://discord.com/developers/docs/resources/channel#thread-member-object),
-/// [extra fields](https://discord.com/developers/docs/topics/gateway-events#thread-member-update-thread-member-update-event-extra-fields).
+/// [Discord docs], [extra fields].
+///
+/// [Discord docs]: https://discord.com/developers/docs/resources/channel#thread-member-object,
+/// [extra fields]: https://discord.com/developers/docs/topics/gateway-events#thread-member-update-thread-member-update-event-extra-fields
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[non_exhaustive]

src/model/guild/role.rs

@@ -10,10 +10,10 @@ use crate::model::utils::is_false;
 
 /// Information about a role within a guild.
 ///
-/// A role represents a set of permissions, and can be attached to one or multiple users. A role has
-/// various miscellaneous configurations, such as being assigned a colour. Roles are unique per
-/// guild and do not cross over to other guilds in any way, and can have channel-specific permission
-/// overrides in addition to guild-level permissions.
+/// A role represents a set of permissions, and can be attached to one or multiple users. A role
+/// has various miscellaneous configurations, such as being assigned a colour. Roles are unique per
+/// guild and do not cross over to other guilds in any way, and can have channel-specific
+/// permission overrides in addition to guild-level permissions.
 ///
 /// [Discord docs](https://discord.com/developers/docs/topics/permissions#role-object).
 #[bool_to_bitflags::bool_to_bitflags]