improve extract docs (#2384)

CHANGES.md

@@ -2,9 +2,12 @@
 
 ## Unreleased - 2021-xx-xx
 ### Changed
-* Asscociated type `FromRequest::Config` was removed. [#2233]
+* Associated type `FromRequest::Config` was removed. [#2233]
+* Inner field made private on `web::Payload`. [#????]
 
 [#2233]: https://github.com/actix/actix-web/pull/2233
+[#????]: https://github.com/actix/actix-web/pull/????
+
 
 ## 4.0.0-beta.9 - 2021-09-09
 ### Added

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

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

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

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
 /// ```

src/types/payload.rs

@@ -43,10 +43,11 @@ use crate::{
 ///     Ok(format!("Request Body Bytes:\n{:?}", bytes))
 /// }
 /// ```
-pub struct Payload(pub crate::dev::Payload);
+pub struct Payload(crate::dev::Payload);
 
 impl Payload {
     /// Unwrap to inner Payload type.
+    #[inline]
     pub fn into_inner(self) -> crate::dev::Payload {
         self.0
     }