Update docs for bon 3.0 release (part 1)
#166
Conversation
|
Caution Review failedThe pull request is closed. WalkthroughThis pull request includes significant modifications to the VitePress configuration, documentation files, and CI workflow for the Changes
Possibly related issues
Possibly related PRs
Suggested reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (16)
website/reference/builder/top-level/finish-fn.md (2)
38-42: Add a comma after "in turn" for better readability.The visibility section is technically accurate, but a small grammatical improvement would help.
-The default visibility is the same as the visibility of the [`builder_type`](./builder-type#vis), which in turn defaults to the visibility of the underlying `struct` or `fn`. +The default visibility is the same as the visibility of the [`builder_type`](./builder-type#vis), which in turn, defaults to the visibility of the underlying `struct` or `fn`.🧰 Tools
🪛 LanguageTool
[uncategorized] ~42-~42: Possible missing comma found.
Context: ...ebuilder_type, which in turn, defaults to the visibility of ...(AI_HYDRA_LEO_MISSING_COMMA)
44-47: Consider adding a documentation example.While the explanation is accurate, it would be helpful to include a small example showing the expected doc comment syntax.
Simple documentation is generated by default. The syntax of this attribute expects a block with doc comments. + +For example: +```rust +#[builder( + finish_fn( + doc { + /// Builds the final object with all configured parameters. + /// + /// # Returns + /// + /// Returns the constructed object. + } + ) +)] +```website/reference/builder.md (1)
Line range hint
1-89: Consider enhancing the documentation structure.While the current documentation is well-organized, consider these improvements to enhance user experience:
- Add a "Quick Start" or "Common Usage" section at the beginning
- Include version compatibility information (especially relevant for 3.0 release)
- Add cross-references to related attributes where applicable
🧰 Tools
🪛 Markdownlint
61-61: Expected: leading_only; Actual: leading_and_trailing; Unexpected trailing pipe
Table pipe style(MD055, table-pipe-style)
website/reference/builder/top-level/builder-type.md (3)
17-29: Consider clarifying field optionality in the long syntax.While line 17 mentions that "all keys are optional", it would be helpful to provide examples of partial configurations to demonstrate this flexibility.
Consider adding examples like:
#[builder( builder_type( name = CustomName, vis = "pub(crate)" // doc is omitted ) )]
44-46: Consider adding an example of visibility inheritance.While the text explains that visibility defaults to the underlying item's visibility, an example would make this clearer.
Consider adding:
pub struct Foo {} // The builder will also be `pub` by default
Line range hint
95-120: Consider improving error example comments.The error example's comments could be more precise about the nature of the conflict.
Consider updating the comment to:
-// `BrushBuilder` builder type name was generated for both -// the struct and the function. This is a compile error +// Error: Multiple definitions of `BrushBuilder` in the same scope +// Both the struct and function builders attempt to use the same namewebsite/reference/builder/top-level/start-fn.md (2)
40-46: Consider enhancing sections with examples.The visibility and documentation sections could be more helpful with concrete examples:
- Show different visibility patterns (e.g.,
pub,pub(crate),"")- Demonstrate custom documentation block syntax
Example enhancement for the doc section:
#[builder( start_fn( doc { /// Creates a new builder for constructing a User. /// /// # Example /// ``` /// let user = User::builder() /// .name("John") /// .build(); /// ``` } ) )]
Line range hint
151-153: Consider clarifying thenewmethod behavior.The paragraph about the
newmethod quirk could be clearer. Consider restructuring it as:-One interesting quirk is that by default the associated method named `new` already generates a starting function under the name `builder`. However, by default, the original method `new` also becomes hidden. By specifying the `#[builder(start_fn = builder)]` explicitly the original method `new` remains exposed. +The associated method `new` has special handling: +- By default, it generates a starting function named `builder` +- The original `new` method is hidden by default +- Adding `#[builder(start_fn = builder)]` explicitly preserves both the original `new` method and the builder syntax🧰 Tools
🪛 LanguageTool
[duplication] ~38-~38: Possible typo: you repeated a word
Context: ...fnT::fn_name()|{fn_name}| Freefn fn_name()|{fn_name}##v...(ENGLISH_WORD_REPEAT_RULE)
website/reference/builder/top-level/derive.md (1)
130-171: Consider enhancing the code examples.The examples could be more educational with these improvements:
- In the "Overly restrictive" example, consider adding a comment explaining the actual compiler error message.
- In the "Fixed" example, explain why
U: Cloneis still needed (becausey: Uneeds to be cloned).Consider updating the examples like this:
// `Rc` can be cloned even if `T` is not `Clone`, but this code // doesn't compile, because the `Clone` impl for `ExampleBuilder` -// conservatively requires `T: Clone` +// conservatively requires `T: Clone`, producing error: +// error[E0277]: the trait bound `T: Clone` is not satisfied builder.clone();#[derive(Builder)] -// Only a bound `U: Clone` is needed in this case +// Only `U: Clone` is needed because: +// - `Rc<T>` implements Clone regardless of T +// - field `y: U` needs to be cloned #[builder(derive(Clone(bounds(U: Clone))))]website/reference/builder/top-level/on.md (2)
86-95: Add missing comma for better readability.Add a comma after the code block for better flow:
-You can use `_` to mark parts of the type to ignore when matching. For example, `Vec<_>` matches `Vec<u32>` or `Vec<String>`. Lifetimes are ignored during matching. +You can use `_` to mark parts of the type to ignore when matching. For example, `Vec<_>` matches `Vec<u32>` or `Vec<String>`. Lifetimes are ignored during matching. -If you want to apply the attributes to all members, you can use the `_` type pattern that matches any type. For example, `#[builder(on(_, into))]`. +If you want to apply the attributes to all members, you can use the `_` type pattern that matches any type. For example, `#[builder(on(_, into))]`. -For optional members the underlying type is matched ignoring the `Option` wrapper. +For optional members, the underlying type is matched ignoring the `Option` wrapper.🧰 Tools
🪛 LanguageTool
[uncategorized] ~94-~94: Possible missing comma found.
Context: ...#[builder(on(_, into))]`. For optional members the underlying type is matched ignoring...(AI_HYDRA_LEO_MISSING_COMMA)
199-201: Add missing article for better grammar.Add the article "a" before "comment":
-We'll be glad if you take a look at the design proposed in that issue and put a 👍 if you like/want this feature or leave comment if you have some more feedback. +We'll be glad if you take a look at the design proposed in that issue and put a 👍 if you like/want this feature or leave a comment if you have some more feedback.🧰 Tools
🪛 LanguageTool
[uncategorized] ~201-~201: You might be missing the article “a” here.
Context: ... if you like/want this feature or leave comment if you have some more feedback.(AI_EN_LECTOR_MISSING_DETERMINER_A)
website/changelog.md (5)
16-16: Add missing comma in the example list.Add a comma before "e.g." for better readability.
-Only parentheses are accepted e.g. `#[builder(finish_fn(...))]` +Only parentheses are accepted, e.g. `#[builder(finish_fn(...))]`🧰 Tools
🪛 LanguageTool
[uncategorized] ~16-~16: Possible missing comma found.
Context: ...attributes syntax. Only parentheses are accepted e.g.#[builder(finish_fn(...))]or `#...(AI_HYDRA_LEO_MISSING_COMMA)
41-41: Improve clarity with proper punctuation.Add a comma to separate the clauses for better readability.
-Add `#[builder(transparent)]` for `Option` fields to opt out from their special handling which makes `bon` treat them as regular required fields. +Add `#[builder(transparent)]` for `Option` fields to opt out from their special handling, which makes `bon` treat them as regular required fields.🧰 Tools
🪛 LanguageTool
[uncategorized] ~41-~41: Possible missing comma found.
Context: ...nfields to opt out from their special handling which makesbon` treat them as regular...(AI_HYDRA_LEO_MISSING_COMMA)
45-45: Add "please" for more polite phrasing.Make the request more polite by adding "please".
-let us know if you need this attribute! +please let us know if you need this attribute!🧰 Tools
🪛 LanguageTool
[style] ~45-~45: This expression usually appears with a “please” in front of it.
Context: ...s://github.com//issues/149), let us know if you need this attribute!). ([#145](h...(INSERT_PLEASE)
57-57: Add missing comma in documentation description.Add a comma for better sentence structure.
-For optional members provide a link +For optional members, provide a link🧰 Tools
🪛 LanguageTool
[uncategorized] ~57-~57: Possible missing comma found.
Context: ...lt value in the docs. - For optional members provide a link to a companion setter. T...(AI_HYDRA_LEO_MISSING_COMMA)
61-61: Add comma before contrasting conjunction.Add a comma before "but" to properly separate independent clauses.
-reported via a Github issue but this provides +reported via a Github issue, but this provides🧰 Tools
🪛 LanguageTool
[uncategorized] ~61-~61: Use a comma before ‘but’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...nd should be reported via a Github issue but this provides an easy temporary workaro...(COMMA_COMPOUND_SENTENCE_2)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
⛔ Files ignored due to path filters (2)
bon-macros/src/builder/builder_gen/input_fn.rsis excluded by!**/*.rsbon/tests/integration/builder/attr_bon.rsis excluded by!**/*.rs
📒 Files selected for processing (11)
- website/.vitepress/config.mts (3 hunks)
- website/changelog.md (1 hunks)
- website/reference/builder.md (1 hunks)
- website/reference/builder/member/overwritable.md (1 hunks)
- website/reference/builder/member/transparent.md (1 hunks)
- website/reference/builder/top-level/builder-type.md (2 hunks)
- website/reference/builder/top-level/derive.md (2 hunks)
- website/reference/builder/top-level/finish-fn.md (1 hunks)
- website/reference/builder/top-level/on.md (4 hunks)
- website/reference/builder/top-level/start-fn.md (2 hunks)
- website/reference/builder/top-level/state-mod.md (1 hunks)
✅ Files skipped from review due to trivial changes (3)
- website/reference/builder/member/overwritable.md
- website/reference/builder/member/transparent.md
- website/reference/builder/top-level/state-mod.md
🧰 Additional context used
🪛 LanguageTool
website/changelog.md
[uncategorized] ~16-~16: Possible missing comma found.
Context: ...attributes syntax. Only parentheses are accepted e.g.#[builder(finish_fn(...))]or `#...(AI_HYDRA_LEO_MISSING_COMMA)
[formatting] ~18-~18: If the ‘because’ clause is essential to the meaning, do not use a comma before the clause.
Context: ..., finish_fn = build, on(Vec<_>, into))], because there is afinish_fn = ...betweeno...(COMMA_BEFORE_BECAUSE)
[uncategorized] ~41-~41: Possible missing comma found.
Context: ...nfields to opt out from their special handling which makesbon` treat them as regular...(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~45-~45: This expression usually appears with a “please” in front of it.
Context: ...s://github.com//issues/149), let us know if you need this attribute!). ([#145](h...(INSERT_PLEASE)
[uncategorized] ~57-~57: Possible missing comma found.
Context: ...lt value in the docs. - For optional members provide a link to a companion setter. T...(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~61-~61: Use a comma before ‘but’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...nd should be reported via a Github issue but this provides an easy temporary workaro...(COMMA_COMPOUND_SENTENCE_2)
website/reference/builder/top-level/finish-fn.md
[duplication] ~36-~36: Possible typo: you repeated a word
Context: ...fnT::fn_name()|{fn_name}| Freefn fn_name()|{fn_name}##v...(ENGLISH_WORD_REPEAT_RULE)
[uncategorized] ~42-~42: Possible missing comma found.
Context: ...ebuilder_type, which in turn, defaults to the visibility of ...(AI_HYDRA_LEO_MISSING_COMMA)
website/reference/builder/top-level/on.md
[uncategorized] ~94-~94: Possible missing comma found.
Context: ...#[builder(on(_, into))]`. For optional members the underlying type is matched ignoring...(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~98-~98: A comma might be missing here.
Context: ...contain several of these separated by a comma e.g.on(_, into, transparent). - [`i...(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[uncategorized] ~100-~100: Loose punctuation mark.
Context: ...ansparent). - [into](../member/into); - [transparent`](../member/transparent...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~201-~201: You might be missing the article “a” here.
Context: ... if you like/want this feature or leave comment if you have some more feedback.(AI_EN_LECTOR_MISSING_DETERMINER_A)
website/reference/builder/top-level/start-fn.md
[duplication] ~38-~38: Possible typo: you repeated a word
Context: ...fnT::fn_name()|{fn_name}| Freefn fn_name()|{fn_name}##v...(ENGLISH_WORD_REPEAT_RULE)
🔇 Additional comments (18)
website/reference/builder/top-level/finish-fn.md (2)
5-25: LGTM! Clear and comprehensive explanation of the attribute.The introduction and syntax sections effectively explain the attribute's purpose and provide well-structured examples for both short and long syntax variants.
27-37: LGTM! Clear presentation of naming rules.The table format effectively presents the default naming rules. Note: The repetition in
fn fn_name()is correct as it represents valid Rust syntax wherefnis the function keyword followed by the function name.🧰 Tools
🪛 LanguageTool
[duplication] ~36-~36: Possible typo: you repeated a word
Context: ...fnT::fn_name()|{fn_name}| Freefn fn_name()|{fn_name}##v...(ENGLISH_WORD_REPEAT_RULE)
website/reference/builder.md (1)
62-62: LGTM! Clear improvement in attribute description.The updated description for
builder_typeis more precise and comprehensive, explicitly stating all aspects that can be overridden (name, visibility, and docs).website/reference/builder/top-level/builder-type.md (2)
1-9: LGTM! Clear and concise introduction.The frontmatter and introduction effectively communicate the purpose and applicability of the
builder_typeattribute.
Line range hint
1-120: Verify documentation consistency across the codebase.Let's ensure the
builder_typeattribute documentation is consistent across all documentation files.✅ Verification successful
Let me analyze the search results to verify documentation consistency. I'll need to check the content of the v1 and v2 documentation to ensure they align with the current version.
After analyzing the documentation across different versions, I can generate the final response regarding the documentation consistency.
Documentation for
builder_typeis consistent with recent changesThe documentation in
website/reference/builder/top-level/builder-type.mdcorrectly reflects:
- The new long syntax with
visanddocoptions- Default naming rules for different contexts
- Examples for all supported cases (structs, free functions, associated methods)
- Proper visibility documentation
The changes are also properly reflected in:
- The changelog entry mentioning the addition of
visanddocsoptions- The main builder reference linking to the detailed documentation
- Cross-references from other documentation files (start-fn.md and finish-fn.md)
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Search for other mentions of builder_type to verify consistency rg -t md "builder_type" website/Length of output: 2709
Script:
#!/bin/bash # Check content of v1 and v2 builder_type documentation cat website/v1/reference/builder.md website/v2/reference/builder.mdLength of output: 61860
website/reference/builder/top-level/start-fn.md (3)
33-38: LGTM! Clear and well-structured table.The table effectively communicates the default naming rules for different syntax patterns.
🧰 Tools
🪛 LanguageTool
[duplication] ~38-~38: Possible typo: you repeated a word
Context: ...fnT::fn_name()|{fn_name}| Freefn fn_name()|{fn_name}##v...(ENGLISH_WORD_REPEAT_RULE)
Line range hint
50-86: LGTM! Well-structured examples with clear highlighting.The examples effectively demonstrate both short and long syntax variants with appropriate code highlighting.
🧰 Tools
🪛 LanguageTool
[duplication] ~38-~38: Possible typo: you repeated a word
Context: ...fnT::fn_name()|{fn_name}| Freefn fn_name()|{fn_name}##v...(ENGLISH_WORD_REPEAT_RULE)
Line range hint
89-150: LGTM! Excellent documentation of function exposure behavior.The section thoroughly explains the interaction between original functions and builder syntax, with clear examples for both free functions and associated methods. The cargo features example is particularly valuable for library maintainers.
website/reference/builder/top-level/derive.md (3)
5-5: LGTM! Clear and attention-grabbing warning.The warning effectively prevents confusion between similar but different attributes.
7-7: LGTM! Clear attribute description.The explanation is precise and includes all necessary details about syntax and supported derives.
122-129: LGTM! Comprehensive explanation of generic type handling.The section effectively explains the problem, solution, and includes a helpful reference for deeper understanding.
Also applies to: 174-178
website/reference/builder/top-level/on.md (3)
Line range hint
1-85: LGTM! Clear introduction with well-structured examples.The introduction effectively explains the
onattribute's purpose and demonstrates its usage across different contexts (structs, free functions, and associated methods).
Line range hint
105-173: LGTM! Comprehensive examples with clear explanations.The examples effectively demonstrate each attribute's usage with appropriate comments explaining the behavior.
Line range hint
174-198: LGTM! Clear explanation of multiple clause usage.The section effectively explains the consecutive clause requirement and demonstrates it with a practical example using different types.
website/.vitepress/config.mts (3)
221-224: LGTM! The new top-level attribute entry is well-structured.The "state_mod" entry follows the established pattern and maintains consistent formatting with other top-level attributes.
247-250: LGTM! The new member attribute entries are properly structured.Both "overwritable" and "transparent" entries maintain consistent formatting and are correctly placed alphabetically within the member attributes section.
Also applies to: 259-262
221-224: Verify that the new documentation pages exist.Let's ensure that the documentation files for the new attributes exist at the referenced paths.
Also applies to: 247-250, 259-262
✅ Verification successful
Documentation files exist at the referenced paths
All the documentation files mentioned in the navigation links are present in the repository:
website/reference/builder/top-level/state-mod.mdwebsite/reference/builder/member/overwritable.mdwebsite/reference/builder/member/transparent.md🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Check if the new documentation files exist echo "Checking for new documentation files..." for path in \ "reference/builder/top-level/state-mod.md" \ "reference/builder/member/overwritable.md" \ "reference/builder/member/transparent.md" do if [ -f "website/$path" ]; then echo "✓ Found: $path" else echo "✗ Missing: $path" fi doneLength of output: 1024
website/changelog.md (1)
13-61: LGTM! Well-structured changelog with clear sections.The changelog follows best practices with:
- Clear marking of breaking changes with
⚠️ - Consistent reference to PR numbers
- Good separation between sections
- Proper versioning format
🧰 Tools
🪛 LanguageTool
[uncategorized] ~16-~16: Possible missing comma found.
Context: ...attributes syntax. Only parentheses are accepted e.g.#[builder(finish_fn(...))]or `#...(AI_HYDRA_LEO_MISSING_COMMA)
[formatting] ~18-~18: If the ‘because’ clause is essential to the meaning, do not use a comma before the clause.
Context: ..., finish_fn = build, on(Vec<_>, into))], because there is afinish_fn = ...betweeno...(COMMA_BEFORE_BECAUSE)
[uncategorized] ~41-~41: Possible missing comma found.
Context: ...nfields to opt out from their special handling which makesbon` treat them as regular...(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~45-~45: This expression usually appears with a “please” in front of it.
Context: ...s://github.com//issues/149), let us know if you need this attribute!). ([#145](h...(INSERT_PLEASE)
[uncategorized] ~57-~57: Possible missing comma found.
Context: ...lt value in the docs. - For optional members provide a link to a companion setter. T...(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~61-~61: Use a comma before ‘but’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...nd should be reported via a Github issue but this provides an easy temporary workaro...(COMMA_COMPOUND_SENTENCE_2)
Veetaha
changed the title
bon 3.0 releasebon 3.0 release (part 1)
Summary by CodeRabbit
New Features
#[derive(Builder)]and#[builder]attributes, enhancing the builder pattern in Rust.overwritableattribute, allowing multiple setter calls for the same member.Bug Fixes
Documentation
Chores