From 2b6bb6ac528c236915d45f86ea267ad77be9dda3 Mon Sep 17 00:00:00 2001
From: Rob Ede <robjtede@icloud.com>
Date: Sat, 11 Sep 2021 16:24:20 +0100
Subject: [PATCH] improve extract docs

---
 src/extract.rs    | 28 +++++++++++++++++++---------
 src/types/form.rs |  2 +-
 src/types/json.rs |  2 +-
 src/types/path.rs |  2 +-
 4 files changed, 22 insertions(+), 12 deletions(-)

diff --git a/src/extract.rs b/src/extract.rs
index 39062dd1c..29fd0d05e 100644
--- a/src/extract.rs
+++ b/src/extract.rs
@@ -13,28 +13,37 @@ use futures_core::ready;
 
 use crate::{dev::Payload, Error, HttpRequest};
 
-/// A type that implements [`FromRequest`] is called an **extractor** and can extract data
-/// from the request. Examples of types that implement this trait are [`Json`], [`Form`], [`Path`].
+/// A type that implements [`FromRequest`] is called an **extractor** and can extract data from
+/// the request. Some types that implement this trait are: [`Json`], [`Header`], and [`Path`].
 ///
+/// # Configuration
 /// An extractor can be customized by injecting the corresponding configuration with one of:
 ///
-/// - [`App::app_data()`](`crate::App::app_data`)
-/// - [`Scope::app_data()`](`crate::Scope::app_data`)
-/// - [`Resource::app_data()`](`crate::Resource::app_data`)
+/// - [`App::app_data()`][crate::App::app_data]
+/// - [`Scope::app_data()`][crate::Scope::app_data]
+/// - [`Resource::app_data()`][crate::Resource::app_data]
 ///
 /// Here are some built-in extractors and their corresponding configuration.
 /// Please refer to the respective documentation for details.
 ///
 /// | Extractor   | Configuration     |
 /// |-------------|-------------------|
+/// | [`Header`]  | _None_            |
+/// | [`Path`]    | [`PathConfig`]    |
 /// | [`Json`]    | [`JsonConfig`]    |
 /// | [`Form`]    | [`FormConfig`]    |
-/// | [`Path`]    | [`PathConfig`]    |
 /// | [`Query`]   | [`QueryConfig`]   |
-/// | [`Payload`] | [`PayloadConfig`] |
-/// | [`String`]  | [`PayloadConfig`] |
 /// | [`Bytes`]   | [`PayloadConfig`] |
+/// | [`String`]  | [`PayloadConfig`] |
+/// | [`Payload`] | [`PayloadConfig`] |
 ///
+/// # Implementing An Extractor
+/// To reduce duplicate code in handlers where extracting certain parts of a request has a common
+/// structure, you can implement `FromRequest` for your own types.
+///
+/// Note that the request payload can only be consumed by one extractor.
+///
+/// [`Header`]: crate::web::Header
 /// [`Json`]: crate::web::Json
 /// [`JsonConfig`]: crate::web::JsonConfig
 /// [`Form`]: crate::web::Form
@@ -47,7 +56,8 @@ use crate::{dev::Payload, Error, HttpRequest};
 /// [`PayloadConfig`]: crate::web::PayloadConfig
 /// [`String`]: FromRequest#impl-FromRequest-for-String
 /// [`Bytes`]: crate::web::Bytes#impl-FromRequest
-#[cfg_attr(docsrs, doc(alias = "Extractor"))]
+/// [`Either`]: crate::web::Either
+#[doc(alias = "extract", alias = "extractor")]
 pub trait FromRequest: Sized {
     /// The associated error which can be returned.
     type Error: Into<Error>;
diff --git a/src/types/form.rs b/src/types/form.rs
index 71100eb97..098a864de 100644
--- a/src/types/form.rs
+++ b/src/types/form.rs
@@ -32,7 +32,7 @@ use crate::{
 /// To extract typed data from a request body, the inner type `T` must implement the
 /// [`DeserializeOwned`] trait.
 ///
-/// Use [`FormConfig`] to configure extraction process.
+/// Use [`FormConfig`] to configure extraction options.
 ///
 /// ```
 /// use actix_web::{post, web};
diff --git a/src/types/json.rs b/src/types/json.rs
index 19443ea96..df01fdb34 100644
--- a/src/types/json.rs
+++ b/src/types/json.rs
@@ -34,7 +34,7 @@ use crate::{
 /// To extract typed data from a request body, the inner type `T` must implement the
 /// [`serde::Deserialize`] trait.
 ///
-/// Use [`JsonConfig`] to configure extraction process.
+/// Use [`JsonConfig`] to configure extraction options.
 ///
 /// ```
 /// use actix_web::{post, web, App};
diff --git a/src/types/path.rs b/src/types/path.rs
index aed897fa9..b58aec18d 100644
--- a/src/types/path.rs
+++ b/src/types/path.rs
@@ -14,7 +14,7 @@ use crate::{
 
 /// Extract typed data from request path segments.
 ///
-/// Use [`PathConfig`] to configure extraction process.
+/// Use [`PathConfig`] to configure extraction option.
 ///
 /// # Examples
 /// ```