Link from class docs to signal collection type

Author: Bromeon

godot-codegen/src/generator/classes.rs

@@ -137,14 +137,16 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
     // Associated "sidecar" module is made public if there are other symbols related to the class, which are not
     // in top-level godot::classes module (notification enums are not in the sidecar, but in godot::classes::notify).
     // This checks if token streams (i.e. code) is empty.
-    let has_sidecar_module = !enums.is_empty() || !builders.is_empty();
+    let has_sidecar_module = !enums.is_empty() || !builders.is_empty() || signal_types.is_some();
 
     let class_doc = docs::make_class_doc(
         class_name,
         base_ident_opt,
         notification_enum.is_some(),
         has_sidecar_module,
+        signal_types.is_some(),
     );
+
     let module_doc = docs::make_module_doc(class_name);
 
     let virtual_trait = virtual_traits::make_virtual_methods_trait(

godot-codegen/src/generator/docs.rs

@@ -9,6 +9,7 @@
 //!
 //! Single module for documentation, rather than having it in each symbol-specific file, so it's easier to keep docs consistent.
 
+use crate::generator::signals;
 use crate::models::domain::{ModName, TyName};
 use crate::special_cases;
 use proc_macro2::Ident;
@@ -18,6 +19,7 @@ pub fn make_class_doc(
     base_ident_opt: Option<Ident>,
     has_notification_enum: bool,
     has_sidecar_module: bool,
+    has_signal_collection: bool,
 ) -> String {
     let TyName { rust_ty, godot_ty } = class_name;
 
@@ -29,15 +31,28 @@ pub fn make_class_doc(
             .to_string()
     };
 
-    let notify_line = if has_notification_enum {
-        format!("* [`{rust_ty}Notification`][crate::classes::notify::{rust_ty}Notification]: notification type\n")
+    let (sidecar_signal_lines, module_name);
+    if has_sidecar_module {
+        let module = ModName::from_godot(&class_name.godot_ty).rust_mod;
+
+        sidecar_signal_lines = format!("* [`{module}`][crate::classes::{module}]: sidecar module with related enum/flag types\n");
+        module_name = Some(module);
+    } else {
+        sidecar_signal_lines = String::new();
+        module_name = None;
+    };
+
+    let signal_line = if has_signal_collection {
+        let signal_coll = signals::make_collection_name(class_name);
+        let module = module_name.expect("signal implies presence of sidecar module");
+
+        format!("* [`{signal_coll}`][crate::classes::{module}::{signal_coll}]: signal collection\n")
     } else {
         String::new()
     };
 
-    let sidecar_line = if has_sidecar_module {
-        let module_name = ModName::from_godot(&class_name.godot_ty).rust_mod;
-        format!("* [`{module_name}`][crate::classes::{module_name}]: sidecar module with related enum/flag types\n")
+    let notify_line = if has_notification_enum {
+        format!("* [`{rust_ty}Notification`][crate::classes::notify::{rust_ty}Notification]: notification type\n")
     } else {
         String::new()
     };
@@ -59,8 +74,9 @@ pub fn make_class_doc(
         {inherits_line}\n\n\
         \
         Related symbols:\n\n\
-        {sidecar_line}\
+        {sidecar_signal_lines}\
         * [`{trait_name}`][crate::classes::{trait_name}]: virtual methods\n\
+        {signal_line}\
         {notify_line}\
         \n\n\
         See also [Godot docs for `{godot_ty}`]({online_link}).\n\n{notes}",

godot-codegen/src/generator/signals.rs

@@ -21,9 +21,9 @@ pub fn make_class_signals(
     class: &Class,
     signals: &[ClassSignal],
     _ctx: &mut Context,
-) -> TokenStream {
+) -> Option<TokenStream> {
     if signals.is_empty() {
-        return TokenStream::new();
+        return None;
     }
 
     let all_params: Vec<SignalParams> = signals
@@ -38,10 +38,16 @@ pub fn make_class_signals(
         .zip(all_params.iter())
         .map(|(signal, params)| make_signal_individual_struct(signal, params));
 
-    quote! {
-        #signal_collection_struct
-        #( #signal_types )*
-    }
+    Some(quote! {
+        #[cfg(since_api = "4.2")]
+        pub use signals::*;
+
+        #[cfg(since_api = "4.2")]
+        mod signals {
+            #signal_collection_struct
+            #( #signal_types )*
+        }
+    })
 }
 
 // Used outside, to document class with links to this type.
@@ -86,17 +92,14 @@ fn make_signal_collection(
 
     quote! {
         #[doc = #collection_docs]
-        #[cfg(since_api = "4.2")]
         pub struct #collection_struct_name<'c> {
             __gd: &'c mut Gd<re_export::#class_name>,
         }
 
-        #[cfg(since_api = "4.2")]
         impl<'c> #collection_struct_name<'c> {
             #( #provider_methods )*
         }
 
-        #[cfg(since_api = "4.2")]
         impl crate::obj::WithSignals for re_export::#class_name {
             type SignalCollection<'c> = #collection_struct_name<'c>;
             #[doc(hidden)]
@@ -126,29 +129,29 @@ fn make_signal_individual_struct(signal: &ClassSignal, params: &SignalParams) ->
     let class_ty = quote! { re_export::#class_name };
     let param_tuple = quote! { ( #type_list ) };
 
+    // Embedded in `mod signals`.
     quote! {
-        #[cfg(since_api = "4.2")]
         pub struct #individual_struct_name<'c> {
-           pub typed: crate::registry::signal::TypedSignal<'c, #class_ty, #param_tuple>,
+           typed: Self::TypedSignal,
         }
 
-        #[cfg(since_api = "4.2")]
-        impl #individual_struct_name<'_> {
+        impl<'c> #individual_struct_name<'c> {
+            type ParamTuple = #param_tuple;
+            type TypedSignal = crate::registry::signal::TypedSignal<'c, #class_ty, Self::ParamTuple>;
+
             pub fn emit(&mut self, #param_list) {
                 self.typed.emit_tuple( (#name_list) );
             }
         }
 
-        #[cfg(since_api = "4.2")]
         impl<'c> std::ops::Deref for #individual_struct_name<'c> {
-            type Target = crate::registry::signal::TypedSignal<'c, #class_ty, #param_tuple>;
+            type Target = Self::TypedSignal;
 
             fn deref(&self) -> &Self::Target {
                 &self.typed
             }
         }
 
-        #[cfg(since_api = "4.2")]
         impl std::ops::DerefMut for #individual_struct_name<'_> {
             fn deref_mut(&mut self) -> &mut Self::Target {
                 &mut self.typed