lib.rs intra-doc links

src/lib.rs

@@ -1,12 +1,12 @@
 //! A general purpose library of common HTTP types
 //!
 //! This crate is a general purpose library for common types found when working
-//! with the HTTP protocol. You'll find `Request` and `Response` types for
+//! with the HTTP protocol. You'll find [`Request`] and [`Response`] types for
 //! working as either a client or a server as well as all of their components.
-//! Notably you'll find `Uri` for what a `Request` is requesting, a `Method`
-//! for how it's being requested, a `StatusCode` for what sort of response came
-//! back, a `Version` for how this was communicated, and
-//! `HeaderName`/`HeaderValue` definitions to get grouped in a `HeaderMap` to
+//! Notably you'll find `Uri` for what a [`Request`] is requesting, a [`Method`]
+//! for how it's being requested, a [`StatusCode`] for what sort of response came
+//! back, a [`Version`] for how this was communicated, and
+//! [`HeaderName`][header::HeaderName]/[`HeaderValue`][header::HeaderName] definitions to get grouped in a [`HeaderMap`] to
 //! work with request/response headers.
 //!
 //! You will notably *not* find an implementation of sending requests or
@@ -19,11 +19,11 @@
 //!
 //! ## Requests and Responses
 //!
-//! Perhaps the main two types in this crate are the `Request` and `Response`
-//! types. A `Request` could either be constructed to get sent off as a client
-//! or it can also be received to generate a `Response` for a server. Similarly
-//! as a client a `Response` is what you get after sending a `Request`, whereas
-//! on a server you'll be manufacturing a `Response` to send back to the client.
+//! Perhaps the main two types in this crate are the [`Request`] and [`Response`]
+//! types. A [`Request`] could either be constructed to get sent off as a client
+//! or it can also be received to generate a [`Response`] for a server. Similarly
+//! as a client a [`Response`] is what you get after sending a [`Request`], whereas
+//! on a server you'll be manufacturing a [`Response`] to send back to the client.
 //!
 //! Each type has a number of accessors for the component fields. For as a
 //! server you might want to inspect a requests URI to dispatch it:
@@ -45,8 +45,8 @@
 //! # fn not_found(_req: Request<()>) -> http::Result<Response<()>> { panic!() }
 //! ```
 //!
-//! On a `Request` you'll also find accessors like `method` to return a
-//! `Method` and `headers` to inspect the various headers. A `Response`
+//! On a [`Request`] you'll also find accessors like [`method`][Request::method] to return a
+//! [`Method`] and [`headers`][Request::method] to inspect the various headers. A [`Response`]
 //! has similar methods for headers, the status code, etc.
 //!
 //! In addition to getters, request/response types also have mutable accessors
@@ -64,7 +64,7 @@
 //! ```
 //!
 //! And finally, one of the most important aspects of requests/responses, the
-//! body! The `Request` and `Response` types in this crate are *generic* in
+//! body! The [`Request`] and [`Response`] types in this crate are *generic* in
 //! what their body is. This allows downstream libraries to use different
 //! representations such as `Request<Vec<u8>>`, `Response<impl Read>`,
 //! `Request<impl Stream<Item = Vec<u8>, Error = _>>`, or even
@@ -87,14 +87,14 @@
 //! Accept: text/html
 //! ```
 //!
-//! Then `"Accept"` is a `HeaderName` while `"text/html"` is a `HeaderValue`.
+//! Then `"Accept"` is a [`HeaderName`][header::HeaderName] while `"text/html"` is a [`HeaderValue`][header::HeaderValue].
 //! Each of these is a dedicated type to allow for a number of interesting
 //! optimizations and to also encode the static guarantees of each type. For
-//! example a `HeaderName` is always a valid `&str`, but a `HeaderValue` may
+//! example a [`HeaderName`][header::HeaderName] is always a valid `&str`, but a [`HeaderValue`] may
 //! not be valid UTF-8.
 //!
 //! The most common header names are already defined for you as constant values
-//! in the `header` module of this crate. For example:
+//! in the [`header`] module of this crate. For example:
 //!
 //! ```
 //! use http::header::{self, HeaderName};
@@ -112,7 +112,7 @@
 //! assert_eq!(name, header::ACCEPT);
 //! ```
 //!
-//! Header values can be created from string literals through the `from_static`
+//! Header values can be created from string literals through the [`from_static`][header::HeaderValue::from_static]
 //! function:
 //!
 //! ```
@@ -133,15 +133,15 @@
 //!
 //! Most HTTP requests and responses tend to come with more than one header, so
 //! it's not too useful to just work with names and values only! This crate also
-//! provides a `HeaderMap` type which is a specialized hash map for keys as
-//! `HeaderName` and generic values. This type, like header names, is optimized
+//! provides a [`HeaderMap`] type which is a specialized hash map for keys as
+//! [`HeaderName`][header::HeaderName] and generic values. This type, like header names, is optimized
 //! for common usage but should continue to scale with your needs over time.
 //!
 //! # URIs
 //!
-//! Each HTTP `Request` has an associated URI with it. This may just be a path
+//! Each HTTP [`Request`] has an associated URI with it. This may just be a path
 //! like `/index.html` but it could also be an absolute URL such as
-//! `https://www.rust-lang.org/index.html`. A `URI` has a number of accessors to
+//! `https://www.rust-lang.org/index.html`. A [`URI`][uri::Uri] has a number of accessors to
 //! interpret it:
 //!
 //! ```