bon v3 docs (part 3)

.githooks/pre-commit

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+FILES=$(git diff --cached --name-only --diff-filter=ACMR | sed 's| |\\ |g')
+[ -z "$FILES" ] && exit 0
+
+echo "> prettier (changed files only)"
+
+# Prettify all selected files
+echo "$FILES" | xargs ./node_modules/.bin/prettier --ignore-unknown --write
+
+echo "> cargo fmt (all files)"
+
+cargo fmt
+
+echo "> taplo fmt (all files)"
+
+taplo fmt
+
+# Add back the modified/prettified files to staging
+echo "$FILES" | xargs git add
+
+exit 0

.github/workflows/ci.yml

@@ -200,6 +200,14 @@ jobs:
       - run: scripts/install/taplo.sh
       - run: taplo fmt --check
 
+  # Check the formatting of Markdown, TS, JS, JSON, YAML files in the repository
+  prettier:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: npx prettier --check .
+
   # Check for typos in the repository based on a static dictionary
   typos:
     runs-on: ubuntu-latest

.github/workflows/release.yml

@@ -10,9 +10,9 @@ on:
   workflow_dispatch:
 
 env:
-    CARGO_TERM_COLOR: always
-    RUST_BACKTRACE: 1
-    CARGO_INCREMENTAL: 0
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+  CARGO_INCREMENTAL: 0
 
 jobs:
   release-rust-crates:

.gitignore

@@ -19,3 +19,5 @@ terraform.tfstate*
 # Terraform variables usually contain sensitive information
 terraform.tfvars
 terraform.tfvars.json
+
+*dbg*

.prettierignore

@@ -0,0 +1,5 @@
+# This file uses terraform's templating syntax rather than YML, so prettier can't parse it
+website/infra/bootstrap/user_data.yml
+
+# Leading whitespace there is intentional as the place for the main issue body
+.github/issue_template.md

README.v3.md

@@ -43,7 +43,6 @@
     </table>
 </div>
 
-
 <!-- #region overview -->
 
 # Overview
@@ -182,7 +181,7 @@ Builders generated by `bon`'s macros use the typestate pattern to ensure all req
 If something is wrong, a compile error will be created. No matter how you use the generated builder a panic is never possible.
 
 | ⭐ Don't forget to give our repo a [star on Github ⭐](https://github.com/elastio/bon)! |
-| --- |
+| --------------------------------------------------------------------------------------- |
 
 ## What's Next?
 
@@ -209,7 +208,6 @@ If you can't figure something out, consult the docs and maybe use the `🔍 Sear
 
 ## Socials
 
-
 <table>
 <tbody>
     <tr>

benchmarks/compilation/README.md

@@ -6,7 +6,7 @@ This is a collection of compilation time benchmarks for the code generated by `b
 
 If you'd like to run the benchmarks yourself, first you need to install the following:
 
-- [`hyperfine`](https://github.com/sharkdp/hyperfine) CLI
+-   [`hyperfine`](https://github.com/sharkdp/hyperfine) CLI
 
 If you are on Linux, just run the following commands to install the dependencies:
 

benchmarks/compilation/results.md

@@ -1,12 +1,12 @@
-| Command | Mean [s] | Min [s] | Max [s] | Relative |
-|:---|---:|---:|---:|---:|
-| `structs_100_fields_10 bon` | 2.319 ± 0.021 | 2.278 | 2.350 | 22.80 ± 2.99 |
-| `structs_100_fields_10 bon-overwritable` | 2.240 ± 0.021 | 2.203 | 2.274 | 22.03 ± 2.89 |
-| `structs_100_fields_10 typed-builder` | 1.849 ± 0.011 | 1.838 | 1.878 | 18.18 ± 2.38 |
-| `structs_100_fields_10 derive_builder` | 1.022 ± 0.016 | 0.995 | 1.043 | 10.05 ± 1.32 |
-| `structs_100_fields_10 ` | 0.104 ± 0.012 | 0.088 | 0.124 | 1.02 ± 0.18 |
-| `structs_10_fields_50 bon` | 2.063 ± 0.017 | 2.044 | 2.100 | 20.28 ± 2.66 |
-| `structs_10_fields_50 bon-overwritable` | 2.029 ± 0.029 | 1.998 | 2.102 | 19.95 ± 2.62 |
-| `structs_10_fields_50 typed-builder` | 2.076 ± 0.016 | 2.048 | 2.101 | 20.41 ± 2.67 |
-| `structs_10_fields_50 derive_builder` | 0.432 ± 0.016 | 0.400 | 0.458 | 4.25 ± 0.58 |
-| `structs_10_fields_50 ` | 0.102 ± 0.013 | 0.084 | 0.130 | 1.00 |
+| Command                                  |      Mean [s] | Min [s] | Max [s] |     Relative |
+| :--------------------------------------- | ------------: | ------: | ------: | -----------: |
+| `structs_100_fields_10 bon`              | 2.319 ± 0.021 |   2.278 |   2.350 | 22.80 ± 2.99 |
+| `structs_100_fields_10 bon-overwritable` | 2.240 ± 0.021 |   2.203 |   2.274 | 22.03 ± 2.89 |
+| `structs_100_fields_10 typed-builder`    | 1.849 ± 0.011 |   1.838 |   1.878 | 18.18 ± 2.38 |
+| `structs_100_fields_10 derive_builder`   | 1.022 ± 0.016 |   0.995 |   1.043 | 10.05 ± 1.32 |
+| `structs_100_fields_10 `                 | 0.104 ± 0.012 |   0.088 |   0.124 |  1.02 ± 0.18 |
+| `structs_10_fields_50 bon`               | 2.063 ± 0.017 |   2.044 |   2.100 | 20.28 ± 2.66 |
+| `structs_10_fields_50 bon-overwritable`  | 2.029 ± 0.029 |   1.998 |   2.102 | 19.95 ± 2.62 |
+| `structs_10_fields_50 typed-builder`     | 2.076 ± 0.016 |   2.048 |   2.101 | 20.41 ± 2.67 |
+| `structs_10_fields_50 derive_builder`    | 0.432 ± 0.016 |   0.400 |   0.458 |  4.25 ± 0.58 |
+| `structs_10_fields_50 `                  | 0.102 ± 0.013 |   0.084 |   0.130 |         1.00 |

benchmarks/runtime/README.md

@@ -6,8 +6,8 @@ This is a collection of runtime benchmarks for the code generated by `bon` crate
 
 If you'd like to run the benchmarks yourself, first you need to install the following:
 
-- `Valgrind`. Its `cachegrind` component is used by [`iai`](https://github.com/bheisler/iai) benchmark to display the instruction counts and cache/RAM hits.
-- `cargo-asm`. It's used to get the resulting assembly code for the benchmarked functions.
+-   `Valgrind`. Its `cachegrind` component is used by [`iai`](https://github.com/bheisler/iai) benchmark to display the instruction counts and cache/RAM hits.
+-   `cargo-asm`. It's used to get the resulting assembly code for the benchmarked functions.
 
 If you are on Ubuntu or Debian, just run the following commands to install the dependencies:
 

bon-cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name    = "bon-cli"
-version = "0.1.0"
+version = "0.2.0"
 
 description = "Dev tool for working with the `bon` crate"
 
@@ -9,7 +9,7 @@ homepage   = "https://bon-rs.com/"
 license    = "MIT OR Apache-2.0"
 repository = "https://github.com/elastio/bon"
 
-publish = false
+publish = true
 
 [[bin]]
 doc  = false
@@ -21,6 +21,6 @@ workspace = true
 
 [dependencies]
 anyhow       = "1.0"
-ra_ap_parser = "=0.0.233"
-ra_ap_syntax = "=0.0.233"
+ra_ap_parser = "=0.0.241"
+ra_ap_syntax = "=0.0.241"
 walkdir      = "2.5"

bon-macros/src/builder/builder_gen/models.rs

@@ -291,7 +291,10 @@ impl BuilderGenCtx {
                     .map(SpannedKey::into_value)
                     .unwrap_or_else(|| {
                         let docs = format!(
-                            "Tools for manipulating the type state of [`{}`].",
+                            "Tools for manipulating the type state of [`{}`].\n\
+                            \n\
+                            See the [detailed guide](https://bon-rs.com/guide/typestate-api) \
+                            that describes how all the pieces here fit together.",
                             builder_type.ident
                         );
 

bon/Cargo.toml

@@ -63,44 +63,8 @@ alloc   = []
 default = ["std"]
 std     = ["alloc"]
 
-# Opts in to the higher MSRV 1.79.0. In this version, Rust stabilized the syntax
-# for bounds in associated type position which can be used to make bounds on generic
-# associated types implied. See the release announcement for more:
-# https://blog.rust-lang.org/2024/06/13/Rust-1.79.0.htmlbounds-in-associated-type-position
-#
-# This feature is useful for the trait `IsComplete` generated by the builder macros.
-# When this feature is enabled, the builder macros use the new syntax for bounds in
-# associated type position, which enables implied `IsSet` bounds for the type state
-# of required members.
-#
-# To understand how this can be used consider the following example:
-#
-# ```rust
-# #[derive(bon::Builder)]
-# struct Example {
-#     a: u32,
-#     b: Option<u32>,
-# }
-#
-# use example_builder::{IsUnset, IsComplete};
-#
-# impl<State: example_builder::State> ExampleBuilder<State> {
-#     fn build_with_default_b(self) -> Example
-#     where
-#         State: IsComplete,
-#         State::B: IsUnset,
-#     {
-#         self.b(42).build()
-#     }
-# }
-# ```
-#
-# This code wouldn't compile without this feature enabled, because `State: IsComplete`
-# wouldn't automatically imply `State::A: IsSet`, so the builder type state returned
-# after `self.b()` doesn't imply that the member `a` is set, and thus `build()`
-# can't be called.
-#
-# Huge thanks to @harudagondi for suggesting the name of this cargo feature!
+# See the explanation of what this feature does in the docs here:
+# https://bon-rs.com/guide/typestate-api/custom-methods#implied-bounds
 implied-bounds = ["bon-macros/implied-bounds"]
 
 # 🔬 Experimental! There may be breaking changes to this feature between *minor* releases,