From 7a1234580c58cef5850f67ad75cce059daf736cc Mon Sep 17 00:00:00 2001 From: Michael Krasnitski Date: Mon, 11 Nov 2024 23:30:53 -0500 Subject: [PATCH] Improve some docs --- src/gateway/client/context.rs | 8 ++++---- src/gateway/client/event_handler.rs | 11 ++++++----- src/gateway/client/mod.rs | 8 ++++---- src/gateway/sharding/mod.rs | 22 ++++++++-------------- src/http/client.rs | 4 +++- src/model/guild/member.rs | 6 ++++-- src/model/guild/role.rs | 8 ++++---- 7 files changed, 33 insertions(+), 34 deletions(-) diff --git a/src/gateway/client/context.rs b/src/gateway/client/context.rs index d5cded2ec55..5287dcefa88 100644 --- a/src/gateway/client/context.rs +++ b/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 diff --git a/src/gateway/client/event_handler.rs b/src/gateway/client/event_handler.rs index d7766c6f617..b6b2da75bdc 100644 --- a/src/gateway/client/event_handler.rs +++ b/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 /// diff --git a/src/gateway/client/mod.rs b/src/gateway/client/mod.rs index 6d8eee2da6f..ca84b3c3cf4 100644 --- a/src/gateway/client/mod.rs +++ b/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 /// diff --git a/src/gateway/sharding/mod.rs b/src/gateway/sharding/mod.rs index f578b9aa6ae..c263bc89193 100644 --- a/src/gateway/sharding/mod.rs +++ b/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,16 +62,13 @@ 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, such as: setting the current +/// activity, reconnecting, syncing guilds, and more. /// -/// 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 /// @@ -79,17 +76,14 @@ use crate::model::user::OnlineStatus; /// [`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, diff --git a/src/http/client.rs b/src/http/client.rs index a6df0701a49..15ee7f4b382 100644 --- a/src/http/client.rs +++ b/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)] diff --git a/src/model/guild/member.rs b/src/model/guild/member.rs index d297749849c..3820c409213 100644 --- a/src/model/guild/member.rs +++ b/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] diff --git a/src/model/guild/role.rs b/src/model/guild/role.rs index 50bc6d45623..1554e1fe011 100644 --- a/src/model/guild/role.rs +++ b/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]