Update documentation to describe new errors

[TedDriggs]

The crate-level docs need to be updated:

• [ ] Explain that we now add two declarations alongside the input struct: The Builder and the BuilderError.
• [ ] Name the variants of the provided BuilderError
• [ ] Provide example of working with the new generated error

[andy128k]

I am experimenting with custom errors and here are some observations.

Box\

Works like a charm, but declaration looks a bit noisy.

// Error is still a `String` here
fn validate_age(builder: &ExampleBuilder) -> Result<(), String> {
    match builder.age {
        Some(age) if age > 150 => Err(format!("Nobody is {} years old", age)),
        _ => Ok(()),
    }
}

#[derive(Debug, Builder)]
#[builder(setter(into), build_fn(validate = "validate_age", error = "Box<dyn std::error::Error>"))]
struct Example {
    name: String,
    age: usize,
}

Anyhow

anyhow::Error cannot convert a String to anyhow::Error, so custom validator needs to be adjusted.

fn validate_age(builder: &ExampleBuilder) -> Result<(), anyhow::Error> {
    match builder.age {
        Some(age) if age > 150 => Err(anyhow!("Nobody is {} years old", age)),
        _ => Ok(()),
    }
}

#[derive(Debug, Builder)]
#[builder(setter(into), build_fn(validate = "validate_age", error = "anyhow::Error"))]
struct Example {
    name: String,
    age: usize,
}

Infallible (nightly)

This doesn't compile

#![feature(never_type, unwrap_infallible)]

#[macro_use]
extern crate derive_builder;

#[derive(Debug, Builder)]
#[builder(setter(into), build_fn(error = "!"))]
struct Example {
    #[builder(default = "\"John Doe\".to_string()")]
    name: String,
    #[builder(default = "17")]
    age: usize,
}

fn main() {
    let person = ExampleBuilder::default()
        .name("Jane Doe")
        .age(200usize)
        .build()
        .into_ok();
    println!("{:?}", person);
}

Compile error is

error: Unknown literal value `!`
 --> derive_builder/examples/infallible.rs:9:42
  |
9 | #[builder(setter(into), build_fn(error = "!"))]
  |                                          ^^^

But the trick with type alias makes it work

#![feature(never_type, unwrap_infallible)]

#[macro_use]
extern crate derive_builder;

type Never = !; // alias

#[derive(Debug, Builder)]
#[builder(setter(into), build_fn(error = "Never"))]
struct Example {
    #[builder(default = "\"John Doe\".to_string()")]
    name: String,
    #[builder(default = "17")]
    age: usize,
}

fn main() {
    let person = ExampleBuilder::default()
        .name("Jane Doe")
        .age(200usize)
        .build()
        .into_ok();
    println!("{:?}", person);
}