Fix clippy::missing_docs_in_private_items triggering for start_fn members (#389)

Author: Veetaha

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

@@ -40,6 +40,7 @@ impl super::BuilderGenCtx {
             let ident = &receiver.field_ident;
             let ty = &receiver.without_self_keyword;
             quote! {
+                /// Value of `self` passed to the starting method, that created the builder
                 #ident: #ty,
             }
         });
@@ -51,8 +52,18 @@ impl super::BuilderGenCtx {
 
         let allows = super::allow_warnings_on_member_types();
 
-        let start_fn_args_fields_idents = self.start_fn_args().map(|member| &member.ident);
-        let start_fn_args_fields_types = self.start_fn_args().map(|member| &member.ty.norm);
+        let start_fn_args_fields = self.start_fn_args().map(|member| {
+            let ident = &member.ident;
+            let ty = &member.ty.norm;
+            let doc = format!(
+                "Value of `{ident}` passed as an argument to the starting function,
+                that created the builder",
+            );
+            quote! {
+                #[doc = #doc]
+                #ident: #ty
+            }
+        });
 
         let named_members_types = self.named_members().map(NamedMember::underlying_norm_ty);
 
@@ -96,7 +107,7 @@ impl super::BuilderGenCtx {
 
                 #receiver_field
 
-                #( #start_fn_args_fields_idents: #start_fn_args_fields_types, )*
+                #( #start_fn_args_fields, )*
 
                 #( #custom_fields_idents: #custom_fields_types, )*
 

bon-sandbox/src/docs_in_private_items.rs

@@ -0,0 +1,81 @@
+//! Tests that make sure `clippy::missing_docs_in_private_items` isn't triggered.
+//! This was created in response to [this issue](https://github.com/elastio/bon/issues/388).
+#![warn(clippy::missing_docs_in_private_items)]
+
+use bon::{bon, builder, Builder};
+
+/// Docs on `ExampleStruct`
+#[derive(Builder)]
+struct ExampleStruct {
+    /// Docs on `start_fn` member
+    #[builder(start_fn)]
+    start_fn: u32,
+
+    /// Docs on `finish_fn` member
+    #[builder(finish_fn)]
+    finish_fn: u32,
+
+    /// Docs on regular member
+    regular: u32,
+}
+
+#[bon]
+impl ExampleStruct {
+    #[builder]
+    const fn selfless_fn(
+        /// Docs on `start_fn` member
+        #[builder(start_fn)]
+        start_fn: u32,
+
+        /// Docs on `finish_fn` member
+        #[builder(finish_fn)]
+        finish_fn: u32,
+
+        /// Docs on regular member
+        regular: u32,
+    ) {
+        let _ = start_fn;
+        let _ = finish_fn;
+        let _ = regular;
+    }
+
+    #[builder]
+    const fn selfful_fn(
+        &self,
+
+        /// Docs on `start_fn` member
+        #[builder(start_fn)]
+        start_fn: u32,
+
+        /// Docs on `finish_fn` member
+        #[builder(finish_fn)]
+        finish_fn: u32,
+
+        /// Docs on regular member
+        regular: u32,
+    ) {
+        let _ = self;
+        let _ = start_fn;
+        let _ = finish_fn;
+        let _ = regular;
+    }
+}
+
+/// Docs on `example` function
+#[builder]
+const fn example_function(
+    /// Docs on `start_fn` member
+    #[builder(start_fn)]
+    start_fn: u32,
+
+    /// Docs on `finish_fn` member
+    #[builder(finish_fn)]
+    finish_fn: u32,
+
+    /// Docs on regular member
+    regular: u32,
+) {
+    let _ = start_fn;
+    let _ = finish_fn;
+    let _ = regular;
+}

bon-sandbox/src/lib.rs

@@ -13,6 +13,7 @@ pub mod overrides;
 pub mod private_builder;
 pub mod state_mod;
 
+mod docs_in_private_items;
 mod reexports;
 
 pub use reexports::{UnexportedBuilder, UnexportedStateMod, UnexportedStateModBuilder};