Add docs for #[builder(derive(Into))]

Author: Veetaha

website/src/reference/builder/top-level/derive.md

@@ -6,7 +6,7 @@ _⚠️ Do not confuse this with `#[derive(bon::Builder)]`⚠️_
 
 Generates additional derives for the builder struct itself. The syntax is similar to the regular `#[derive(...)]` attribute, but it must be wrapped in `#[builder(derive(...))]`. Expects one or more of the supported derives separated by a comma.
 
-The following derives are supported: `Clone`, `Debug`.
+The following derives are supported: [`Clone`, `Debug`](#clone-and-debug-derives), [`Into`](#into-derive).
 
 ::: warning
 The format of the `Debug` output of the builder is not stable, and it may change between patch versions of `bon`.
@@ -20,7 +20,7 @@ The format of the `Debug` output of the builder is not stable, and it may change
 use bon::Builder;
 
 #[derive(Builder)]
-#[builder(derive(Clone, Debug))] // [!code highlight]
+#[builder(derive(Clone, Debug, Into))] // [!code highlight]
 struct Example {
     name: String,
     is_admin: bool,
@@ -41,19 +41,24 @@ assert_eq!(
     r#"ExampleBuilder { name: "Bon" }"#
 );
 
-// Finish building
-let example = builder.is_admin(true).build();
+let example: Example = builder
+    .is_admin(true)
+    // We can use `From<ExampleBuilder>` to `Example` instead of
+    // calling .build()
+    .into();
 ```
 
 ```rust [Function]
 use bon::builder;
 
-#[builder(derive(Clone, Debug))] // [!code highlight]
+#[builder(derive(Clone, Debug, Into))] // [!code highlight]
 fn example(
     name: String,
     is_admin: bool,
     level: Option<u32>,
-) {}
+) -> u32 {
+    level.unwrap_or(99)
+}
 
 let builder = example().name("Bon".to_owned());
 
@@ -69,8 +74,13 @@ assert_eq!(
     r#"ExampleBuilder { name: "Bon" }"#
 );
 
-// Finish building
-builder.is_admin(true).call();
+let example: u32 = builder
+    .is_admin(true)
+    // We can use `From<ExampleBuilder>` to `Example` instead of
+    // calling .build()
+    .into();
+
+assert_eq!(example, 99);
 ```
 
 ```rust [Method]
@@ -81,12 +91,14 @@ struct Example;
 
 #[bon]
 impl Example {
-    #[builder(derive(Clone, Debug))] // [!code highlight]
+    #[builder(derive(Clone, Debug, Into))] // [!code highlight]
     fn method(
         name: String,
         is_admin: bool,
         level: Option<u32>,
-    ) {}
+    ) -> u32 {
+        99
+    }
 
     #[builder(derive(Debug))]
     fn method_with_self(&self) {}
@@ -106,8 +118,14 @@ assert_eq!(
     r#"ExampleMethodBuilder { name: "Bon" }"#
 );
 
-// Finish building
-builder.is_admin(true).call();
+
+let example: u32 = builder
+    .is_admin(true)
+    // We can use `From<ExampleBuilder>` to `Example` instead of
+    // calling .build()
+    .into();
+
+assert_eq!(example, 99);
 
 // The debug output of the builder for methods with `self` includes
 // the special `self` field with the receiver.
@@ -119,9 +137,11 @@ assert_eq!(
 
 :::
 
-## Generic types handling
+## `Clone` and `Debug` derives
+
+### Generic types handling
 
-If the underlying `struct` or `fn` contains generic type parameters, then the generated impl block will include a `where` bound requiring the respective trait (`Clone` or `Debug`) to be implemented by all of them. This follows the behaviour of the [standard `derive` macros](https://doc.rust-lang.org/std/clone/trait.Clone.html#derivable).
+If the underlying `struct` or `fn` contains generic type parameters, then the generated impl block will include a `where` bound requiring the respective trait to be implemented by all of them. This follows the behaviour of the [standard `derive` macros](https://doc.rust-lang.org/std/clone/trait.Clone.html#derivable).
 
 This works fine in most cases, but sometimes the generated bounds may be overly restrictive. To fix that, you can manually specify the bounds using the syntax `#[builder(derive(Trait(bounds(...))))]`, where `...` is a comma-separated list of `where` bounds.
 
@@ -177,7 +197,7 @@ If you'd like to know why this attribute is this dumb and doesn't just add a `wh
 
 :::
 
-## Compile errors
+### Compile errors
 
 _Requires_ that all members of the builder including the receiver (if this is a builder for an associated method) implement the target trait. For example, this doesn't compile because not all members implement `Clone`:
 
@@ -196,3 +216,35 @@ struct Example {
     cloneable: u32
 }
 ```
+
+## `Into` derive
+
+Somewhat obviously, but `Into` derive actually generates a `From` implementation, providing the `Into` trait implementation automatically via the [blanket `impl` in std](https://doc.rust-lang.org/stable/std/convert/trait.From.html#generic-implementations).
+
+::: details See an example of what code it generates:
+
+(you can even write it manually actually)
+
+```rust
+use bon::Builder;
+
+#[derive(Builder)]
+struct Example {
+    x1: String,
+}
+
+// This is what #[builder(derive(Into))] would generate:
+impl<S: example_builder::IsComplete> From<ExampleBuilder<S>> for Example {
+    fn from(builder: ExampleBuilder<S>) -> Self {
+        ExampleBuilder::build(builder)
+    }
+}
+```
+
+:::
+
+Note that `#[builder(derive(Into))]` is quite limited. Here are some things it doesn't support:
+
+-   `async` functions, because `From::from()` is synchronous
+-   `unsafe` functions, because `From::from()` is safe
+-   Members marked with [`#[builder(finish_fn)]`](../member/finish_fn) because `From::from()` doesn't accept arguments