From dcbb1941c5b489b5a9f367c3ae7f6f8c3c6275a9 Mon Sep 17 00:00:00 2001
From: Sergio Benitez <sb@sergio.bz>
Date: Tue, 29 Jun 2021 03:33:44 -0700
Subject: [PATCH] Explicitly mention multipart support in guide.

---
 site/guide/4-requests.md | 42 +++++++++++++++++++++++++++++++---------
 1 file changed, 33 insertions(+), 9 deletions(-)

diff --git a/site/guide/4-requests.md b/site/guide/4-requests.md
index 08a0d387..5445d01b 100644
--- a/site/guide/4-requests.md
+++ b/site/guide/4-requests.md
@@ -761,15 +761,16 @@ struct Task<'r> {
 fn new(task: Form<Task<'_>>) { /* .. */ }
 ```
 
-The [`Form`] type implements the `FromData` trait as long as its generic
-parameter implements the [`FromForm`] trait. In the example, we've derived the
-`FromForm` trait automatically for the `Task` structure. `FromForm` can be
-derived for any structure whose fields implement [`FromForm`], or equivalently,
-[`FromFormField`]. If a `POST /todo` request arrives, the form data will
-automatically be parsed into the `Task` structure. If the data that arrives
-isn't of the correct Content-Type, the request is forwarded. If the data doesn't
-parse or is simply invalid, a customizable error is returned. As before, a
-forward or failure can be caught by using the `Option` and `Result` types:
+[`Form`] is data guard as long as its generic parameter implements the
+[`FromForm`] trait. In the example, we've derived the `FromForm` trait
+automatically for `Task`. `FromForm` can be derived for any structure whose
+fields implement [`FromForm`], or equivalently, [`FromFormField`].
+
+If a `POST /todo` request arrives, the form data will automatically be parsed
+into the `Task` structure. If the data that arrives isn't of the correct
+Content-Type, the request is forwarded. If the data doesn't parse or is simply
+invalid, a customizable error is returned. As before, a forward or failure can
+be caught by using the `Option` and `Result` types:
 
 ```rust
 # use rocket::{post, form::Form};
@@ -779,6 +780,29 @@ forward or failure can be caught by using the `Option` and `Result` types:
 fn new(task: Option<Form<Task<'_>>>) { /* .. */ }
 ```
 
+### Multipart
+
+Multipart forms are handled transparently, with no additional effort. Most
+`FromForm` types can parse themselves from the incoming data stream. For
+example, here's a form and route that accepts a multipart file upload using
+[`TempFile`]:
+
+```rust
+# #[macro_use] extern crate rocket;
+
+use rocket::form::Form;
+use rocket::fs::TempFile;
+
+#[derive(FromForm)]
+struct Upload<'r> {
+    save: bool,
+    file: TempFile<'r>,
+}
+
+#[post("/upload", data = "<upload>")]
+fn upload_form(upload: Form<Upload<'_>>) { /* .. */ }
+```
+
 [`Form`]: @api/rocket/form/struct.Form.html
 [`FromForm`]: @api/rocket/form/trait.FromForm.html
 [`FromFormField`]: @api/rocket/form/trait.FromFormField.html