docs(http): basic request module documentation

twilight-http/src/request/audit_reason.rs

@@ -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.
     ///

twilight-http/src/request/mod.rs

@@ -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;