Improve documentation of axum::Form (#2289)

.github/workflows/CI.yml

@@ -2,7 +2,7 @@ name: CI
 
 env:
   CARGO_TERM_COLOR: always
-  MSRV: '1.63'
+  MSRV: '1.65'
 
 on:
   push:

axum-extra/Cargo.toml

@@ -2,7 +2,7 @@
 categories = ["asynchronous", "network-programming", "web-programming"]
 description = "Extra utilities for axum"
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.65"
 homepage = "https://github.com/tokio-rs/axum"
 keywords = ["http", "web", "framework"]
 license = "MIT"

axum-extra/README.md

@@ -14,7 +14,7 @@ This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in
 
 ## Minimum supported Rust version
 
-axum-extra's MSRV is 1.63.
+axum-extra's MSRV is 1.65.
 
 ## Getting Help
 

axum-extra/src/typed_header.rs

@@ -105,7 +105,7 @@ where
     }
 }
 
-/// Rejection used for [`TypedHeader`](TypedHeader).
+/// Rejection used for [`TypedHeader`].
 #[cfg(feature = "typed-header")]
 #[derive(Debug)]
 pub struct TypedHeaderRejection {

axum-macros/Cargo.toml

@@ -2,7 +2,7 @@
 categories = ["asynchronous", "network-programming", "web-programming"]
 description = "Macros for axum"
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.65"
 homepage = "https://github.com/tokio-rs/axum"
 keywords = ["axum"]
 license = "MIT"

axum-macros/README.md

@@ -14,7 +14,7 @@ This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in
 
 ## Minimum supported Rust version
 
-axum-macros's MSRV is 1.63.
+axum-macros's MSRV is 1.65.
 
 ## Getting Help
 

axum/CHANGELOG.md

@@ -61,7 +61,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **fixed:** Fix `.source()` of composite rejections ([#2030])
 - **fixed:** Allow unreachable code in `#[debug_handler]` ([#2014])
 - **change:** Update tokio-tungstenite to 0.19 ([#2021])
-- **change:** axum's MSRV is now 1.63 ([#2021])
+- **change:** axum's MSRV is now 1.65 ([#2021])
 - **added:** Implement `Handler` for `T: IntoResponse` ([#2140])
 - **added:** Implement `IntoResponse` for `(R,) where R: IntoResponse` ([#2143])
 - **changed:** For SSE, add space between field and value for compatibility ([#2149])

axum/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.6.16"
 categories = ["asynchronous", "network-programming", "web-programming::http-server"]
 description = "Web framework that focuses on ergonomics and modularity"
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.65"
 homepage = "https://github.com/tokio-rs/axum"
 keywords = ["http", "web", "framework"]
 license = "MIT"

axum/README.md

@@ -112,7 +112,7 @@ This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in
 
 ## Minimum supported Rust version
 
-axum's MSRV is 1.63.
+axum's MSRV is 1.65.
 
 ## Examples
 

axum/src/extract/path/mod.rs

@@ -348,7 +348,7 @@ impl fmt::Display for ErrorKind {
     }
 }
 
-/// Rejection type for [`Path`](super::Path) if the captured routes params couldn't be deserialized
+/// Rejection type for [`Path`] if the captured routes params couldn't be deserialized
 /// into the expected type.
 #[derive(Debug)]
 pub struct FailedToDeserializePathParams(PathDeserializationError);

axum/src/form.rs

@@ -12,9 +12,18 @@ use serde::Serialize;
 ///
 /// # As extractor
 ///
-/// If used as an extractor `Form` will deserialize the query parameters for `GET` and `HEAD`
+/// If used as an extractor, `Form` will deserialize form data from the request,
-/// requests and `application/x-www-form-urlencoded` encoded request bodies for other methods. It
+/// specifically:
-/// supports any type that implements [`serde::Deserialize`].
+///
+/// - If the request has a method of `GET` or `HEAD`, the form data will be read
+///   from the query string (same as with [`Query`])
+/// - If the request has a different method, the form will be read from the body
+///   of the request. It must have a `content-type` of
+///   `application/x-www-form-urlencoded` for this to work. If you want to parse
+///   `multipart/form-data` request bodies, use [`Multipart`] instead.
+///
+/// This matches how HTML forms are sent by browsers by default.
+/// In both cases, the inner type `T` must implement [`serde::Deserialize`].
 ///
 /// ⚠️ Since parsing form data might require consuming the request body, the `Form` extractor must be
 /// *last* if there are multiple extractors in a handler. See ["the order of
@@ -37,11 +46,11 @@ use serde::Serialize;
 /// }
 /// ```
 ///
-/// Note that `Content-Type: multipart/form-data` requests are not supported. Use [`Multipart`]
-/// instead.
-///
 /// # As response
 ///
+/// `Form` can also be used to encode any type that implements
+/// [`serde::Serialize`] as `application/x-www-form-urlencoded`
+///
 /// ```rust
 /// use axum::Form;
 /// use serde::Serialize;
@@ -56,6 +65,7 @@ use serde::Serialize;
 /// }
 /// ```
 ///
+/// [`Query`]: crate::extract::Query
 /// [`Multipart`]: crate::extract::Multipart
 #[cfg_attr(docsrs, doc(cfg(feature = "form")))]
 #[derive(Debug, Clone, Copy, Default)]