Document FooBuilderError (#238)

Fixes #190

derive_builder/src/lib.rs

@@ -28,6 +28,7 @@
 //! ```rust
 //! # #[macro_use]
 //! # extern crate derive_builder;
+//! # use derive_builder::UninitializedFieldError;
 //! #
 //! # struct Lorem {
 //! #     ipsum: u32,
@@ -38,6 +39,8 @@
 //! struct LoremBuilder {
 //!     ipsum: Option<u32>,
 //! }
+//! # // bodge for testing:
+//! # type LoremBuilderError = UninitializedFieldError;
 //!
 //! #[allow(dead_code)]
 //! impl LoremBuilder {
@@ -47,11 +50,11 @@
 //!         new
 //!     }
 //!
-//!     fn build(&self) -> Result<Lorem, String> {
+//!     fn build(&self) -> Result<Lorem, LoremBuilderError> {
 //!         Ok(Lorem {
 //!             ipsum: Clone::clone(self.ipsum
 //!                 .as_ref()
-//!                 .ok_or("ipsum must be initialized")?),
+//!                 .ok_or(LoremBuilderError::from(UninitializedFieldError::new("ipsum")))?),
 //!         })
 //!     }
 //! }
@@ -551,6 +554,59 @@
 //! # fn main() {}
 //! ```
 //!
+//! # Error return type from autogenerated `build` function
+//!
+//! By default, `build` returns an autogenerated error type:
+//!
+//! ```rust
+//! # extern crate derive_builder;
+//! # use derive_builder::UninitializedFieldError;
+//! # use std::fmt::{self, Display};
+//! #
+//! #[doc="Error type for LoremBuilder"]
+//! #[derive(Debug)]
+//! #[non_exhaustive]
+//! pub enum LoremBuilderError { // where `LoremBuilder` is the name of the builder struct
+//!     /// Uninitialized field
+//!     UninitializedField(&'static str),
+//!     /// Custom validation error
+//!     ValidationError(String),
+//! }
+//!
+//! impl From<String> for LoremBuilderError {
+//!     fn from(s: String) -> Self { Self::ValidationError(s) }
+//! }
+//! impl From<UninitializedFieldError> for LoremBuilderError { // ...
+//! # fn from(s: UninitializedFieldError) -> Self { todo!() } }
+//! impl Display for LoremBuilderError { // ...
+//! # fn fmt(&self, _: &mut fmt::Formatter) -> fmt::Result { todo!() } }
+//! impl std::error::Error for LoremBuilderError {}
+//! ```
+//!
+//! Alternatively, you can specify your own error type:
+//! ```rust
+//! # #[macro_use]
+//! # extern crate derive_builder;
+//! # use derive_builder::UninitializedFieldError;
+//! #
+//! #[derive(Builder, Debug, PartialEq)]
+//! #[builder(build_fn(error = "OurLoremError"))]
+//! struct Lorem {
+//!     pub ipsum: u32,
+//! }
+//!
+//! struct OurLoremError(String);
+//!
+//! impl From<UninitializedFieldError> for OurLoremError {
+//!     fn from(ufe: UninitializedFieldError) -> OurLoremError { OurLoremError(ufe.to_string()) }
+//! }
+//!
+//! # fn main() {
+//! let err: OurLoremError = LoremBuilder::default().build().unwrap_err();
+//! assert_eq!(&err.0, "Field not initialized: ipsum");
+//! # }
+//! ```
+//!
 //! # **`#![no_std]`** Support (on Nightly)
 //!
 //! You can activate support for `#![no_std]` by adding `#[builder(no_std)]` to your struct

derive_builder_core/src/builder.rs

@@ -51,26 +51,7 @@ use Setter;
 ///     ValidationError(::derive_builder::export::core::string::String),
 /// }
 ///
-/// impl ::derive_builder::export::core::convert::From<&'static str> for FooBuilderError {
-///     fn from(s: &'static str) -> Self {
-///         Self::UninitializedField(s)
-///     }
-/// }
-///
-/// impl ::derive_builder::export::core::convert::From<::derive_builder::export::core::string::String> for FooBuilderError {
-///     fn from(s: ::derive_builder::export::core::string::String) -> Self {
-///         Self::ValidationError(s)
-///     }
-/// }
-///
-/// impl ::derive_builder::export::core::fmt::Display for FooBuilderError {
-///     fn fmt(&self, f: &mut ::derive_builder::export::core::fmt::Formatter) -> ::derive_builder::export::core::fmt::Result {
-///         match self {
-///             Self::UninitializedField(ref field) => write!(f, "`{}` must be initialized", field),
-///             Self::ValidationError(ref error) => write!(f, "{}", error),
-///         }
-///     }
-/// }
+/// impl ::derive_builder::export::core::convert::From<... various ...> for FooBuilderError {}
 ///
 /// #[cfg(not(no_std))]
 /// impl std::error::Error for FooBuilderError {}