Clean up docs for IntoResponseHeaders

This commit is contained in:
David Pedersen 2022-01-23 18:23:37 +01:00
parent f96111851d
commit 2546be04f6

View file

@ -144,38 +144,17 @@ pub trait IntoResponse {
} }
/// Trait for generating response headers. /// Trait for generating response headers.
///
/// **Note: If you see this trait not being implemented in an error message, you are almost
/// certainly being mislead by the compiler¹. Look for the following snippet in the output and
/// check [`IntoResponse`]'s documentation if you find it:**
///
/// ```text
/// note: required because of the requirements on the impl of `IntoResponse` for `<type>`
/// ```
///
/// Any type that implements this trait automatically implements `IntoResponse` as well, but can
/// also be used in a tuple like `(StatusCode, Self)`, `(Self, impl IntoResponseHeaders)`,
/// `(StatusCode, Self, impl IntoResponseHeaders, impl IntoResponse)` and so on.
///
/// This trait can't currently be implemented outside of axum.
///
/// ¹ See also [this rustc issue](https://github.com/rust-lang/rust/issues/22590)
pub trait IntoResponseHeaders { pub trait IntoResponseHeaders {
/// The return type of [`.into_headers()`]. /// The return type of `into_headers`.
/// ///
/// The iterator item is a `Result` to allow the implementation to return a server error /// The iterator item is a [`Result`] to allow the implementation to return a server error
/// instead. /// instead.
/// ///
/// The header name is optional because `HeaderMap`s iterator doesn't yield it multiple times /// The header name is optional because [`HeaderMap`]s iterator doesn't yield it multiple times
/// for headers that have multiple values, to avoid unnecessary copies. /// for headers that have multiple values, to avoid unnecessary copies.
#[doc(hidden)]
type IntoIter: IntoIterator<Item = Result<(Option<HeaderName>, HeaderValue), Response>>; type IntoIter: IntoIterator<Item = Result<(Option<HeaderName>, HeaderValue), Response>>;
/// Attempt to turn `self` into a list of headers. /// Attempt to turn `self` into a list of headers.
///
/// In practice, only the implementation for `axum::response::Headers` ever returns `Err(_)`.
#[doc(hidden)]
fn into_headers(self) -> Self::IntoIter; fn into_headers(self) -> Self::IntoIter;
} }