fix: pass through docs for server functions (#1164)

server_fn_macro/src/lib.rs

@@ -5,12 +5,13 @@
 //!
 //! This crate contains the implementation of the server_fn macro. [server_macro_impl] can be used to implement custom versions of the macro for different frameworks that allow users to pass a custom context from the server to the server function.
 
-use proc_macro2::{Literal, TokenStream as TokenStream2};
+use proc_macro2::{Literal, Span, TokenStream as TokenStream2};
 use proc_macro_error::abort;
-use quote::quote;
+use quote::{quote, quote_spanned};
 use syn::{
     parse::{Parse, ParseStream},
     punctuated::Punctuated,
+    spanned::Spanned,
     *,
 };
 
@@ -201,7 +202,23 @@ pub fn server_macro_impl(
         None => "CARGO_MANIFEST_DIR",
     };
 
+    let link_to_server_fn = format!(
+        "Serialized arguments for the [`{fn_name_as_str}`] server \
+         function.\n\n"
+    );
+    let args_docs = quote! {
+        #[doc = #link_to_server_fn]
+    };
+
+    let docs = body
+        .docs
+        .iter()
+        .map(|(doc, span)| quote_spanned!(*span=> #[doc = #doc]))
+        .collect::<TokenStream2>();
+
     Ok(quote::quote! {
+        #args_docs
+        #docs
         #[derive(Clone, Debug, ::serde::Serialize, ::serde::Deserialize)]
         pub struct #struct_name {
             #(#fields),*
@@ -239,11 +256,13 @@ pub fn server_macro_impl(
             }
         }
 
+        #docs
         #[cfg(feature = "ssr")]
         #vis async fn #fn_name(#(#fn_args),*) #output_arrow #return_ty {
             #block
         }
 
+        #docs
         #[cfg(not(feature = "ssr"))]
         #[allow(unused_variables)]
         #vis async fn #fn_name(#(#fn_args_2),*) #output_arrow #return_ty {
@@ -316,6 +335,7 @@ struct ServerFnBody {
     pub output_arrow: Token![->],
     pub return_ty: syn::Type,
     pub block: Box<Block>,
+    pub docs: Vec<(String, Span)>,
 }
 
 /// The custom rusty variant of parsing rsx!
@@ -340,6 +360,28 @@ impl Parse for ServerFnBody {
 
         let block = input.parse()?;
 
+        let docs = attrs
+            .iter()
+            .filter_map(|attr| {
+                let Meta::NameValue(attr ) = &attr.meta else {
+                return None
+            };
+                if !attr.path.is_ident("doc") {
+                    return None;
+                }
+
+                let value = match &attr.value {
+                    syn::Expr::Lit(lit) => match &lit.lit {
+                        syn::Lit::Str(s) => Some(s.value()),
+                        _ => return None,
+                    },
+                    _ => return None,
+                };
+
+                Some((value.unwrap_or_default(), attr.path.span()))
+            })
+            .collect();
+
         Ok(Self {
             vis,
             async_token,
@@ -352,6 +394,7 @@ impl Parse for ServerFnBody {
             return_ty,
             block,
             attrs,
+            docs,
         })
     }
 }