setters

Applies to: struct fields function arguments method arguments

Overrides name, visibility and docs for setters.

The config is tree-structured with overrides precedence explained in the next paragraph.

#[builder(
    setters(
        name = custom_name,
        vis = "pub(crate)",
        doc {
            /// Custom docs for all setters
        },
        // Can be specified simultaneously with the `doc {...}` block too
        doc(default(skip)),

        // There is short and long syntax (select only one)
        some_fn = custom_name,
        some_fn(
            name = custom_name,
            vis = "pub(crate)",
            doc {
                /// Custom docs for the `some_fn` setter
            }
        ),

        // There is short and long syntax (select only one)
        option_fn = custom_name,
        option_fn(
            name = custom_name,
            vis = "pub(crate)",
            doc {
                /// Custom docs for the `option_fn` setter
            }
        )
    )
)]

The main use case for this attribute is making generated setters private to wrap them with custom methods. See Custom Methods for details.

Config precedence

The keys some_fn and option_fn are available only for optional members that have a pair of setters.

The root-level name, vis, docs are still available for both required and optional setters. They can be overwritten at some_fn and option_fn level individually.

Example

#[derive(bon::Builder)]
struct Example {
    #[builder(setters(name = foo, some_fn = bar))]
    member: Option<u32>,
}

// Name of `some_fn` that accepts the non-None value was overridden
Example::builder().bar(2).build();

// Name of `option_fn` was derived from the root-level `setters(name)`
Example::builder().maybe_foo(Some(2)).build();

name

The default name for setters is chosen according to the following rules:

Member type	Default
Required	{member}
Optional	some_fn = {member} option_fn = maybe_{member}

This attribute is different from #[builder(name)] because it overrides only the names of setters. It doesn't influence the name of the member in the builder's typestate API. This attribute also has higher precedence than #[builder(name)].

vis

The visibility must be enclosed with quotes. Use "" or "pub(self)" for private visibility.

The default visibility is the same as the visibility of the builder_type, which in turn, defaults to the visibility of the underlying struct or fn.

doc

Simple documentation is generated by default. This configuration can take two forms depending on the delimiter used. Both of these can be used separately or together at the same time.

doc {...}

The curly-brace delimited block expects doc comments that will override the main content of the documentation.

doc {
    /// Doc comments
}

Note that this doesn't influence the auto-generated docs header. Use doc(...) to configure the header instead.

doc(default(skip))

Skips the inclusion of the default value of the member in the auto-generated documentation header for optional setters that use the #[builder(default)] attribute.

This attribute can also be configured via the top-level #[builder(on(_, ...))] attribute.

See the example usage of this attribute and how it changes the docs here.