Skip to content

Commit

Permalink
docs(http): basic request module documentation (twilight-rs#2100)
Browse files Browse the repository at this point in the history
Add basic documentation for the `twilight_http::request` module,
highlighting the typed builders, multipart form support, low-level
request construction, and audit log reason support. Included is a short
example of how to use audit logs.

This is a response to a support ticket with regard to how adding reasons
to requests isn't very discoverable:
<https://discord.com/channels/745809834183753828/1059877180487770112>
  • Loading branch information
zeylahellyer authored Jan 29, 2023
1 parent a76334a commit 704a789
Show file tree
Hide file tree
Showing 2 changed files with 46 additions and 0 deletions.
4 changes: 4 additions & 0 deletions twilight-http/src/request/audit_reason.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
use twilight_validate::request::ValidationError;

/// Attach a reason for a request.
///
/// Reasons are associated with the audit log entries that are automatically
/// created for certain requests.
pub trait AuditLogReason<'a>: private::Sealed {
/// Attach an audit log reason to the request.
///
Expand Down
42 changes: 42 additions & 0 deletions twilight-http/src/request/mod.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,45 @@
//! Typed request builders, [multipart form support], a [manual request builder]
//! for low-level request construction, and [audit log reason] support.
//!
//! # Request Builders
//!
//! Requests are created in the form of builders. These can be `await`ed to
//! receive a [`Response`]. Every route of Discord's API has its own builder:
//! creating a message is performed via the [`CreateMessage`] builder; updating
//! a guild is done via [`UpdateGuild`]; and so on. All typed request builders
//! are instantiated via the primary [`Client`]. When the library doesn't yet
//! support a new feature or fine-grained support is required, requests can be
//! manually built via [`RequestBuilder`].
//!
//! # Audit Log Reasons
//!
//! Audit log reasons can be added to supported requests via the
//! [`AuditLogReason`] trait:
//!
//! ```no_run
//! # #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! # use twilight_model::id::Id;
//! #
//! # let guild_id = Id::new(1);
//! # let user_id = Id::new(2);
//! use twilight_http::{client::Client, request::AuditLogReason};
//!
//! let client = Client::new(std::env::var("DISCORD_TOKEN")?);
//! client
//! .delete_ban(guild_id, user_id)
//! .reason("ban expired")?
//! .await?;
//! # Ok(()) }
//! ```
//!
//! [`Client`]: crate::client::Client
//! [`CreateMessage`]: channel::message::CreateMessage
//! [`Response`]: crate::Response
//! [`UpdateGuild`]: guild::UpdateGuild
//! [audit log reason]: AuditLogReason
//! [manual request builder]: RequestBuilder
//! [multipart form support]: Form

pub mod application;
pub mod attachment;
pub mod channel;
Expand Down

0 comments on commit 704a789

Please sign in to comment.