Merge pull request #1353 from Yarwin/preserve-docs-in-signal

Preserve doc comments for signal.

Author: Yarwin

godot-macros/src/class/data_models/signal.rs

@@ -109,6 +109,8 @@ struct SignalDetails<'a> {
     signal_name_str: String,
     /// `#[cfg(..)] #[cfg(..)]`
     signal_cfg_attrs: Vec<&'a venial::Attribute>,
+    /// `///` `#[doc = ...]`
+    signal_doc_attrs: Vec<&'a venial::Attribute>,
     /// `MyClass_MySignal`
     individual_struct_name: Ident,
     /// Visibility, e.g. `pub(crate)`
@@ -146,6 +148,11 @@ impl<'a> SignalDetails<'a> {
             .into_iter()
             .collect();
 
+        // Preserve docs.
+        let signal_doc_attrs = util::extract_doc_attrs(external_attributes)
+            .into_iter()
+            .collect();
+
         let param_tuple = quote! { ( #( #param_types, )* ) };
         let signal_name = &fn_signature.name;
         let individual_struct_name = format_ident!("__godot_Signal_{}_{}", class_name, signal_name);
@@ -169,6 +176,7 @@ impl<'a> SignalDetails<'a> {
             signal_name,
             signal_name_str: fn_signature.name.to_string(),
             signal_cfg_attrs,
+            signal_doc_attrs,
             individual_struct_name,
             vis_marker: vis_marker.clone(),
             // vis_classified,
@@ -285,6 +293,7 @@ impl SignalCollection {
             signal_name,
             signal_name_str,
             signal_cfg_attrs,
+            signal_doc_attrs,
             individual_struct_name,
             vis_marker,
             ..
@@ -293,6 +302,7 @@ impl SignalCollection {
         self.provider_methods.push(quote! {
             // Deliberately not #[doc(hidden)] for IDE completion.
             #(#signal_cfg_attrs)*
+            #(#signal_doc_attrs)*
             // Note: this could be `pub` always and would still compile (maybe warning with the following message).
             //   associated function `SignalCollection::my_signal` is reachable at visibility `pub(crate)`
             //

godot-macros/src/util/mod.rs

@@ -275,6 +275,15 @@ pub(crate) fn extract_cfg_attrs(
     attrs.iter().filter(|attr| is_cfg_or_cfg_attr(attr))
 }
 
+pub(crate) fn extract_doc_attrs(
+    attrs: &[venial::Attribute],
+) -> impl IntoIterator<Item = &venial::Attribute> {
+    attrs.iter().filter(|attr| {
+        attr.get_single_path_segment()
+            .is_some_and(|attr_name| attr_name == "doc")
+    })
+}
+
 #[cfg(before_api = "4.3")]
 pub fn make_virtual_tool_check() -> TokenStream {
     quote! {

itest/rust/src/register_tests/func_test.rs

@@ -192,6 +192,17 @@ impl GdSelfObj {
     #[cfg(any())]
     fn cfg_removes_signal();
 
+    /// Sample docstring.
+    ///
+    /// Impossible to check by other means than manually, but it is still nice to have some documentation.
+    #[signal]
+    fn docstring_is_preserved_in_signal();
+
+    /// Sample docstring, to watch if it causes any issues with `#[cfg(...)]`.
+    #[signal]
+    #[cfg(any())]
+    fn cfg_removes_signal_with_docstring();
+
     #[func]
     fn fail_to_update_internal_value_due_to_conflicting_borrow(
         &mut self,