docs: improve ext module overview

src/ext/mod.rs

@@ -1,4 +1,39 @@
-//! HTTP extensions.
+//! Extensions for HTTP messages in Hyper.
+//!
+//! This module provides types and utilities that extend the capabilities of HTTP requests and responses
+//! in Hyper. Extensions are additional pieces of information or features that can be attached to HTTP
+//! messages via the [`http::Extensions`] map, which is
+//! accessible through methods like [`http::Request::extensions`] and [`http::Response::extensions`].
+//!
+//! # What are extensions?
+//!
+//! Extensions allow Hyper to associate extra metadata or behaviors with HTTP messages, beyond the standard
+//! headers and body. These can be used by advanced users and library authors to access protocol-specific
+//! features, track original header casing, handle informational responses, and more.
+//!
+//! # How to access extensions
+//!
+//! Extensions are stored in the `Extensions` map of a request or response. You can access them using:
+//!
+//! ```rust
+//! # let response = http::Response::new(());
+//! if let Some(ext) = response.extensions().get::<hyper::ext::ReasonPhrase>() {
+//!     // use the extension
+//! }
+//! ```
+//!
+//! # Extension Groups
+//!
+//! The extensions in this module can be grouped as follows:
+//!
+//! - **HTTP/1 Reason Phrase**: [`ReasonPhrase`] — Access non-canonical reason phrases in HTTP/1 responses.
+//! - **Informational Responses**: [`on_informational`] — Register callbacks for 1xx HTTP/1 responses on the client.
+//! - **Header Case Tracking**: Internal types for tracking the original casing and order of headers as received.
+//! - **HTTP/2 Protocol Extensions**: [`Protocol`] — Access the `:protocol` pseudo-header for Extended CONNECT in HTTP/2.
+//!
+//! Some extensions are only available for specific protocols (HTTP/1 or HTTP/2) or use cases (client, server, FFI).
+//!
+//! See the documentation on each item for details about its usage and requirements.
 
 #[cfg(all(any(feature = "client", feature = "server"), feature = "http1"))]
 use bytes::Bytes;
@@ -29,10 +64,24 @@ pub(crate) use informational::OnInformational;
 pub(crate) use informational::{on_informational_raw, OnInformationalCallback};
 
 #[cfg(feature = "http2")]
-/// Represents the `:protocol` pseudo-header used by
-/// the [Extended CONNECT Protocol].
+/// Extension type representing the `:protocol` pseudo-header in HTTP/2.
 ///
-/// [Extended CONNECT Protocol]: https://datatracker.ietf.org/doc/html/rfc8441#section-4
+/// The `Protocol` extension allows access to the value of the `:protocol` pseudo-header
+/// used by the [Extended CONNECT Protocol](https://datatracker.ietf.org/doc/html/rfc8441#section-4).
+/// This extension is only sent on HTTP/2 CONNECT requests, most commonly with the value `websocket`.
+///
+/// # Example
+///
+/// ```rust
+/// use hyper::ext::Protocol;
+/// use http::{Request, Method, Version};
+///
+/// let mut req = Request::new(());
+/// *req.method_mut() = Method::CONNECT;
+/// *req.version_mut() = Version::HTTP_2;
+/// req.extensions_mut().insert(Protocol::from_static("websocket"));
+/// // Now the request will include the `:protocol` pseudo-header with value "websocket"
+/// ```
 #[derive(Clone, Eq, PartialEq)]
 pub struct Protocol {
     inner: h2::ext::Protocol,