From 47faac6080b5ce9d6ec33a06ccb6a914b8054966 Mon Sep 17 00:00:00 2001
From: Sergio Benitez <sb@sergio.bz>
Date: Mon, 2 Oct 2023 11:59:03 -0700
Subject: [PATCH] Document that '&[u8]' is a form guard.

---
 core/lib/src/form/from_form.rs       |  4 +++-
 core/lib/src/form/from_form_field.rs | 23 ++++++++++++++++++++++-
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/core/lib/src/form/from_form.rs b/core/lib/src/form/from_form.rs
index 726ca208..f44be8cf 100644
--- a/core/lib/src/form/from_form.rs
+++ b/core/lib/src/form/from_form.rs
@@ -120,7 +120,7 @@ use crate::http::uncased::AsUncased;
 /// | IP Address         | _inherit_   | **no default**    | No     | Yes    | [`IpAddr`], [`Ipv4Addr`], [`Ipv6Addr`]             |
 /// | Socket Address     | _inherit_   | **no default**    | No     | Yes    | [`SocketAddr`], [`SocketAddrV4`], [`SocketAddrV6`] |
 /// | [`TempFile`]       | _inherit_   | **no default**    | Yes    | Yes    | Data limits apply. See [`TempFile`].               |
-/// | [`Capped<C>`]      | _inherit_   | **no default**    | Yes    | Yes    | `C` is `&str`, `String`, or `TempFile`.            |
+/// | [`Capped<C>`]      | _inherit_   | **no default**    | Yes    | Yes    | `C` is `&str`, `String`, `&[u8]` or `TempFile`.     |
 /// | [`time::Date`]     | _inherit_   | **no default**    | No     | Yes    | `%F` (`YYYY-MM-DD`). HTML "date" input.            |
 /// | [`time::DateTime`] | _inherit_   | **no default**    | No     | Yes    | `%FT%R` or `%FT%T` (`YYYY-MM-DDTHH:MM[:SS]`)       |
 /// | [`time::Time`]     | _inherit_   | **no default**    | No     | Yes    | `%R` or `%T` (`HH:MM[:SS]`)                        |
@@ -628,6 +628,8 @@ impl<'v, T: FromForm<'v> + 'v> FromForm<'v> for Vec<T> {
     }
 }
 
+// impl_strict_from_form_field_from_capped!(Vec<u8>);
+
 #[doc(hidden)]
 pub struct MapContext<'v, K, V> where K: FromForm<'v>, V: FromForm<'v> {
     opts: Options,
diff --git a/core/lib/src/form/from_form_field.rs b/core/lib/src/form/from_form_field.rs
index 9035ad38..d03ee386 100644
--- a/core/lib/src/form/from_form_field.rs
+++ b/core/lib/src/form/from_form_field.rs
@@ -28,11 +28,32 @@ use crate::form::prelude::*;
 /// }
 /// ```
 ///
+/// # Semantics
+///
+/// The implementation of `FromForm` for a `T: FromFormField` type operates as
+/// follows:
+///
+///   * When parsing is **strict**, the parser accepts the _first_ value or data
+///     field with the corresponding field name and calls `T::from_value()` or
+///     `T::from_data()` with the field's value, respectively. If more than one
+///     field value is seen, an [`ErrorKind::Duplicate`) is emitted. If no
+///     matching field is seen, an [`ErrorKind::Missing`] is emitted. Otherwise,
+///     the result from the call is emitted.
+///
+///   * When parsing is **lenient**, the parser accepts the first _expected_
+///     value or data field with the corresponding field name and calls
+///     `T::from_value()` or `T::from_data()` with the field's value,
+///     respectively. Unexpected values, identified by returning an
+///     [`ErrorKind::Unexpected`] from `from_value()` or `from_data()` are
+///     ignored. Any additional fields with a matching field name are ignored.
+///     If no matching field is seen and `T` has a default, it is used,
+///     otherwise an [`ErrorKind::Missing`] is emitted.
+///
 /// # Deriving
 ///
 /// `FromFormField` can be derived for C-like enums, where the generated
 /// implementation case-insensitively parses fields with values equal to the
-/// name of the variant or the value in `field(value = "...")`.
+/// name of the variant or the value in `field()`.
 ///
 /// ```rust
 /// # use rocket::form::FromFormField;