From 2389aad546fcc857c3daf2ce7a168e0408e187d5 Mon Sep 17 00:00:00 2001
From: Manuel Cillero <manuel@cillero.es>
Date: Wed, 28 Feb 2024 00:10:23 +0100
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20doc=20comments=20for=20bui?=
 =?UTF-8?q?lder=20pattern=20functions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 helpers/pagetop-macros/src/lib.rs | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/helpers/pagetop-macros/src/lib.rs b/helpers/pagetop-macros/src/lib.rs
index 6937b0a9..062e9860 100644
--- a/helpers/pagetop-macros/src/lib.rs
+++ b/helpers/pagetop-macros/src/lib.rs
@@ -45,19 +45,32 @@ pub fn fn_with(_attr: TokenStream, item: TokenStream) -> TokenStream {
         })
         .collect();
 
+    let fn_with_name = fn_name.replace("alter_", "with_");
+
     #[rustfmt::skip]
     let fn_with = parse_str::<ItemFn>(concat_string!("
-        pub fn ", fn_name.replace("alter_", "with_"), "(mut self, ", args.join(", "), ") -> Self {
+        pub fn ", fn_with_name, "(mut self, ", args.join(", "), ") -> Self {
             self.", fn_name, "(", param.join(", "), ");
             self
         }
     ").as_str()).unwrap();
 
+    #[rustfmt::skip]
+    let fn_alter_doc = concat_string!(
+        "<p id=\"method.", fn_with_name, "\">",
+        "Use <code class=\"code-header\"> <a class=\"fn\" href=\"#method.", fn_with_name, "\">",
+        fn_with_name,
+        "</a>(self, …) -> Self </code> to apply the <a href=\"#method.new\">builder pattern</a>.",
+        "</p>"
+    );
+
     let fn_alter = fn_item.into_token_stream();
 
     let expanded = quote! {
+        #[doc(hidden)]
         #fn_with
         #[inline]
+        #[doc = #fn_alter_doc]
         #fn_alter
     };
     expanded.into()