From 9e9c708a1605cdd39cccd226a41e5af48baa5fbc Mon Sep 17 00:00:00 2001
From: Sergio Benitez <sb@sergio.bz>
Date: Sun, 23 May 2021 18:18:24 -0700
Subject: [PATCH] Expose 'Context::{push_error,push_errors}'.

Closes #1582.

Co-authored-by: Francois Stephany <francois@tamere.eu>
---
 core/lib/src/form/context.rs | 54 ++++++++++++++++++++++++++++++------
 core/lib/src/form/error.rs   |  9 ++++--
 2 files changed, 52 insertions(+), 11 deletions(-)

diff --git a/core/lib/src/form/context.rs b/core/lib/src/form/context.rs
index f43e0485..a2e2ca35 100644
--- a/core/lib/src/form/context.rs
+++ b/core/lib/src/form/context.rs
@@ -299,19 +299,57 @@ impl<'v> Context<'v> {
         self.status
     }
 
-    pub(crate) fn push_error(&mut self, e: Error<'v>) {
-        self.status = std::cmp::max(self.status, e.status());
-        match e.name {
+    /// Inject a single error `error` into the context.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use rocket::post;
+    /// # type T = String;
+    /// use rocket::http::Status;
+    /// use rocket::form::{Form, Contextual, Error};
+    ///
+    /// #[post("/submit", data = "<form>")]
+    /// fn submit(mut form: Form<Contextual<'_, T>>) {
+    ///     let error = Error::validation("a good error message")
+    ///         .with_name("field_name")
+    ///         .with_value("some field value");
+    ///
+    ///     form.context.push_error(error);
+    /// }
+    /// ```
+    pub fn push_error(&mut self, error: Error<'v>) {
+        self.status = std::cmp::max(self.status, error.status());
+        match error.name {
             Some(ref name) => match self.errors.get_mut(name) {
-                Some(errors) => errors.push(e),
-                None => { self.errors.insert(name.clone(), e.into()); },
+                Some(errors) => errors.push(error),
+                None => { self.errors.insert(name.clone(), error.into()); },
             }
-            None => self.form_errors.push(e)
+            None => self.form_errors.push(error)
         }
     }
 
-    pub(crate) fn push_errors(&mut self, errors: Errors<'v>) {
-        errors.into_iter().for_each(|e| self.push_error(e))
+    /// Inject all of the errors in `errors` into the context.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use rocket::post;
+    /// # type T = String;
+    /// use rocket::http::Status;
+    /// use rocket::form::{Form, Contextual, Error};
+    ///
+    /// #[post("/submit", data = "<form>")]
+    /// fn submit(mut form: Form<Contextual<'_, T>>) {
+    ///     let error = Error::validation("a good error message")
+    ///         .with_name("field_name")
+    ///         .with_value("some field value");
+    ///
+    ///     form.context.push_errors(vec![error]);
+    /// }
+    /// ```
+    pub fn push_errors<E: Into<Errors<'v>>>(&mut self, errors: E) {
+        errors.into().into_iter().for_each(|e| self.push_error(e))
     }
 }
 
diff --git a/core/lib/src/form/error.rs b/core/lib/src/form/error.rs
index 24026808..a83e2b08 100644
--- a/core/lib/src/form/error.rs
+++ b/core/lib/src/form/error.rs
@@ -74,19 +74,22 @@ pub struct Errors<'v>(Vec<Error<'v>>);
 ///
 /// # Contructing
 ///
-/// An `Error` can be constructed from anything that an [`ErrorKind`] can be
-/// constructed from. See [`ErrorKind`](ErrorKind#constructing).
+/// An `Error` can be constructed via [`Error::validation()`],
+/// [`Error::custom()`], or anything that an [`ErrorKind`] can be constructed
+/// from. See [`ErrorKind`](ErrorKind#constructing).
 ///
 /// ```rust
 /// use rocket::form::Error;
 ///
-/// fn at_most_10() -> Result<usize, Error<'static>> {
+/// fn at_most_10_not_even() -> Result<usize, Error<'static>> {
 ///     // Using `From<PartIntError> => ErrorKind::Int`.
 ///     let i: usize = "foo".parse()?;
 ///
 ///     if i > 10 {
 ///         // `From<(Option<isize>, Option<isize>)> => ErrorKind::OutOfRange`
 ///         return Err((None, Some(10isize)).into());
+///     } else if i % 2 == 0 {
+///         return Err(Error::validation("integer cannot be even"));
 ///     }
 ///
 ///     Ok(i)