Improve the guide section

Author: Veetaha

website/.vitepress/config.mts

@@ -160,8 +160,8 @@ export default defineConfig({
                             link: "/guide/basics/positional-members",
                         },
                         {
-                            text: "Inspecting",
-                            link: "/guide/basics/inspecting",
+                            text: "Derives for Builders",
+                            link: "/guide/basics/derives-for-builders",
                         },
                         {
                             text: "Documenting",

website/src/guide/basics/derives-for-builders.md

@@ -0,0 +1,33 @@
+# Derives for Builders
+
+You can specify some extra derives on the generated builder struct itself via the top-level [`#[builder(derive(...))]`](../../reference/builder/top-level/derive) attribute.
+
+For example, if you want to inspect the values set in the builder for debugging purposes you can derive the `Debug` trait for your builder.
+
+```rust
+use bon::builder;
+
+#[builder(derive(Debug))] // [!code highlight]
+fn example(
+    name: String,
+    is_admin: bool,
+    level: Option<u32>,
+) {}
+
+let builder = example().name("Bon".to_owned());
+
+// This will output the current state of the builder to `stderr`
+dbg!(&builder);
+
+// You can also format the debug output to `String`:
+assert_eq!(
+    format!("{builder:?}"),
+    // Only the fields that were set will be output
+    r#"ExampleBuilder { name: "Bon" }"#
+);
+
+// Finish building
+builder.is_admin(true).call();
+```
+
+You can also derive the `Clone` and `Into` traits for your builder using this same attribute. See more details in the [reference for the `#[builder(derive(...))]` attribute](../../reference/builder/top-level/derive).

website/src/guide/basics/inspecting.md

@@ -137,9 +137,9 @@ assert_eq!(
 
 :::
 
-## `Clone` and `Debug` derives
+## `Clone` and `Debug` Derives
 
-### Generic types handling
+### 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 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).
 
@@ -248,3 +248,25 @@ Note that `#[builder(derive(Into))]` is quite limited. Here are some things it d
 -   `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
+
+### Use Cases
+
+This derive is most useful to reduce the boilerplate of calling the finishing function when the result of building is passed to some other function that accepts `impl Into<T>`.
+
+```rust
+use bon::Builder;
+
+#[derive(Builder)]
+#[builder(derive(Into))]
+struct Example {
+    x1: u32,
+}
+
+fn take_example(value: impl Into<Example>) { /* */ }
+
+take_example(
+    // You can omit the call to `build()` here
+    Example::builder()
+        .x1(99)
+)
+```