Clean up docs for macro-generated connect_* methods

Bromeon · Bromeon · commit 43b4b1c199f3 · 2025-05-25T11:25:32.000+02:00
diff --git a/godot-core/src/registry/signal/connect_builder.rs b/godot-core/src/registry/signal/connect_builder.rs
@@ -16,17 +16,9 @@ use std::fmt::Debug;
 
 /// Builder for customizing signal connections.
 ///
-/// Allows a high degree of customization for connecting signals, while maintaining complete type safety.
+/// Allows a high degree of customization for connecting [`TypedSignal`], while maintaining complete type safety.
 ///
-/// <div class="warning">
-/// <strong>Warning:</strong>
-/// Exact type parameters are subject to change and not part of the public API. We could annotate <code>#[doc(hidden)]</code>, but it would make
-/// things harder to understand. Thus, try not to name the <code>ConnectBuilder</code> type in your code; most connection setup doesn't need it.
-/// </div>
-// If naming the type becomes a requirement, there may be some options:
-// - Use a type alias in the module or TypedSignal, exposing only public parameters. This would work for constructor, but not all transformations.
-// - Pack multiple types together into "type lists", i.e. custom structs carrying the type state. For a user, this would appear as one type,
-// - which could also be #[doc(hidden)]. However, this may make the trait resolution more complex and worsen error messages, so not done now.
+/// See the [Signals](https://godot-rust.github.io/book/register/signals.html) chapter in the book for a general introduction and examples.
 ///
 /// # Customization
 /// Customizing your signal connection must be done **before** providing the function being connected
@@ -39,13 +31,36 @@ use std::fmt::Debug;
 /// - [`flags()`][Self::flags]: Provide one or multiple [`ConnectFlags`][crate::classes::object::ConnectFlags], possibly combined with bitwise OR.
 ///
 /// # Finalizing
-/// After customizing your builder, you can register the connection by using one of the following methods:
-/// - [`connect()`][Self::connect]: Connect a global/associated function or a closure.
-/// - [`connect_self()`][Self::connect_self]: Connect a method or closure that runs on the signal emitter.
-/// - [`connect_other()`][Self::connect_other]: Connect a method or closure that runs on a separate object.
-/// - [`connect_sync()`](#method.connect_sync): Connect a global/associated function or closure that should be callable across threads. \
-///   Allows signal to be emitted from other threads. \
-///   Requires `Send` + `Sync` bounds on the provided function/method, and is only available for the `experimental-threads` Cargo feature.
+/// After customizing your builder, you can register the connection with various `connect_*` functions.
+///
+/// To connect to **methods** (member functions) with a signal object, you have the following combinations:
+///
+/// | Signal object | 1st parameter `&mut C`                         | 1st parameter `&mut Gd<C>`                   |
+/// |---------------|------------------------------------------------|----------------------------------------------|
+/// | `self`        | [`connect_self_mut`][Self::connect_self_mut]   | [`connect_self_gd`][Self::connect_self_gd]   |
+/// | other object  | [`connect_other_mut`][Self::connect_other_mut] | [`connect_other_gd`][Self::connect_other_gd] |
+///
+/// <br>
+///
+/// For **global functions, associated functions and closures**, you can use the following APIs:
+/// - [`connect()`][Self::connect]: Connect any function running on the same thread as the signal emitter.
+/// - [`connect_sync()`](#method.connect_sync): Connect a global/associated function or closure that should be callable across threads.
+///   Allows signals to be emitted from other threads.
+///   - Requires `Send` + `Sync` bounds on the provided function.
+///   - Is only available for the Cargo feature `experimental-threads`.
+///
+/// # Implementation and documentation notes
+/// See [`TypedSignal` docs](struct.TypedSignal.html#implementation-and-documentation-notes) for a background on the `connect_*` API design.
+///
+/// <div class="warning">
+/// <strong>Warning:</strong>
+/// Exact type parameters are subject to change and not part of the public API. Since it's a type-state API, new states might require new
+/// type parameters. Thus, try not to name the <code>ConnectBuilder</code> type in your code; most connection setup doesn't need it.
+/// </div>
+// If naming the type becomes a requirement, there may be some options:
+// - Use a type alias in the module or TypedSignal, exposing only public parameters. This would work for constructor, but not all transformations.
+// - Pack multiple types together into "type lists", i.e. custom structs carrying the type state. For a user, this would appear as one type,
+// - which could also be #[doc(hidden)]. However, this may make the trait resolution more complex and worsen error messages, so not done now.
 #[must_use]
 pub struct ConnectBuilder<'ts, 'c, C: WithSignals, Ps> {
     parent_sig: &'ts TypedSignal<'c, C, Ps>,
@@ -120,10 +135,8 @@ where
 }
 
 macro_rules! impl_builder_connect {
-    ($( $args:ident : $Ps:ident ),*) => {
-        // --------------------------------------------------------------------------------------------------------------------------------------
-        // SignalReceiver
-
+    ($( #[$attr:meta] )? $( $args:ident : $Ps:ident ),*) => {
+        $( #[$attr] )?
         impl<C: WithSignals, $($Ps: Debug + FromGodot + 'static),*>
             ConnectBuilder<'_, '_, C, ($($Ps,)*)> {
             /// Connect a non-member function (global function, associated function or closure).
@@ -135,7 +148,11 @@ macro_rules! impl_builder_connect {
             /// sig.connect(|arg| { /* closure */ });
             /// ```
             ///
-            /// - To connect to a method on the object that owns this signal, use [`connect_self()`][Self::connect_self].
+            /// # Related APIs
+            /// - To connect to a method on the object that owns this signal, use [`connect_self_mut()`][Self::connect_self_mut] or
+            ///   [`connect_self_gd()`][Self::connect_self_gd].
+            /// - To connect to methods on other objects, use [`connect_other_mut()`][Self::connect_other_mut] or
+            ///   [`connect_other_gd()`][Self::connect_other_gd].
             /// - If you need [`connect flags`](ConnectFlags), call [`flags()`](Self::flags) before this.
             /// - If you need cross-thread signals, use [`connect_sync()`](#method.connect_sync) instead (requires feature "experimental-threads").
             pub fn connect<F, R>(self, mut function: F)
@@ -151,7 +168,8 @@ macro_rules! impl_builder_connect {
 
             /// Connect a method with `&mut self` as the first parameter (user classes only).
             ///
-            /// - Use [`connect_self_gd()`][Self::connect_self_gd] to receive `Gd<Self>` instead and avoid implicit `bind_mut()` on emit.
+            /// # Related APIs
+            /// - Use [`connect_self_gd()`][Self::connect_self_gd] to receive `Gd<Self>` instead and avoid implicit `bind_mut()` on emit.  \
             ///   For engine classes, `&mut self` is not supported at all.
             /// - To connect to methods on other objects, use [`connect_other_mut()`][Self::connect_other_mut].
             /// - If you need [connect flags](ConnectFlags), call [`flags()`](Self::flags) before this.
@@ -172,6 +190,7 @@ macro_rules! impl_builder_connect {
 
             /// Connect a method with `&mut Gd<Self>` as the first parameter (user + engine classes).
             ///
+            /// # Related APIs
             /// - If your class `C` is user-defined and you'd like to have an automatic `bind_mut()` and receive `&mut self`, then
             ///   use [`connect_self_mut()`][Self::connect_self_mut] instead.
             /// - To connect to methods on other objects, use [`connect_other_gd()`][Self::connect_other_gd].
@@ -196,9 +215,10 @@ macro_rules! impl_builder_connect {
             /// - `&OtherC`, as long as `OtherC` is a user class that contains a `Base<T>` field (it implements the
             ///   [`WithBaseField`](crate::obj::WithBaseField) trait).
             ///
-            /// ---
-            ///
-            /// - To connect to methods on the object that owns this signal, use [`connect_self_mut()`][Self::connect_self].
+            /// # Related APIs
+            /// - Use [`connect_other_gd()`][Self::connect_other_gd] to receive `Gd<Self>` instead and avoid implicit `bind_mut()` on emit.  \
+            ///   For engine classes, `&mut self` is not supported at all.
+            /// - To connect to methods on the object that owns this signal, use [`connect_self_mut()`][Self::connect_self_mut].
             /// - If you need [connect flags](ConnectFlags), call [`flags()`](Self::flags) before this.
             /// - If you need cross-thread signals, use [`connect_sync()`](#method.connect_sync) instead (requires feature "experimental-threads").
             pub fn connect_other_mut<F, R, OtherC>(self, object: &impl ToSignalObj<OtherC>, mut method: F)
@@ -223,8 +243,7 @@ macro_rules! impl_builder_connect {
             /// - `&OtherC`, as long as `OtherC` is a user class that contains a `Base<T>` field (it implements the
             ///   [`WithBaseField`](crate::obj::WithBaseField) trait).
             ///
-            /// ---
-            ///
+            /// # Related APIs
             /// - To connect to methods on the object that owns this signal, use [`connect_self_gd()`][Self::connect_self_gd].
             /// - If you need [connect flags](ConnectFlags), call [`flags()`](Self::flags) before this.
             /// - If you need cross-thread signals, use [`connect_sync()`](#method.connect_sync) instead (requires feature "experimental-threads").
@@ -271,14 +290,14 @@ macro_rules! impl_builder_connect {
     };
 }
 
-impl_builder_connect!();
-impl_builder_connect!(arg0: P0);
-impl_builder_connect!(arg0: P0, arg1: P1);
-impl_builder_connect!(arg0: P0, arg1: P1, arg2: P2);
-impl_builder_connect!(arg0: P0, arg1: P1, arg2: P2, arg3: P3);
-impl_builder_connect!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4);
-impl_builder_connect!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5);
-impl_builder_connect!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6);
-impl_builder_connect!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7);
-impl_builder_connect!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8);
-impl_builder_connect!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8, arg9: P9);
+impl_builder_connect!(#[doc(hidden)] );
+impl_builder_connect!(#[doc(hidden)] arg0: P0);
+impl_builder_connect!(#[doc(hidden)] arg0: P0, arg1: P1);
+impl_builder_connect!(               arg0: P0, arg1: P1, arg2: P2);
+impl_builder_connect!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3);
+impl_builder_connect!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4);
+impl_builder_connect!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5);
+impl_builder_connect!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6);
+impl_builder_connect!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7);
+impl_builder_connect!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8);
+impl_builder_connect!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8, arg9: P9);
diff --git a/godot-core/src/registry/signal/typed_signal.rs b/godot-core/src/registry/signal/typed_signal.rs
@@ -43,11 +43,13 @@ impl<C: WithBaseField> ToSignalObj<C> for C {
 /// Short-lived type, only valid in the scope of its surrounding object type `C`, for lifetime `'c`. The generic argument `Ps` represents
 /// the parameters of the signal, thus ensuring the type safety.
 ///
+/// See the [Signals](https://godot-rust.github.io/book/register/signals.html) chapter in the book for a general introduction and examples.
+///
 /// The [`WithSignals::SignalCollection`] struct returns multiple signals with distinct, code-generated types, but they all implement
 /// `Deref` and `DerefMut` to `TypedSignal`. This allows you to either use the concrete APIs of the generated types, or the more generic
 /// ones of `TypedSignal`.
 ///
-/// # Connecting a signal to a receiver.
+/// # Connecting a signal to a receiver
 /// Receiver functions are functions that are called when a signal is emitted. You can connect a signal in many different ways:
 /// - [`connect()`][Self::connect]: Connect a global/associated function or a closure.
 /// - [`connect_self()`][Self::connect_self]: Connect a method or closure that runs on the signal emitter.
@@ -60,8 +62,19 @@ impl<C: WithBaseField> ToSignalObj<C> for C {
 ///
 /// For generic use, you can also use [`emit_tuple()`][Self::emit_tuple], which does not provide parameter names.
 ///
-/// # More information
-/// See the [Signals](https://godot-rust.github.io/book/register/signals.html) chapter in the book for a detailed introduction and examples.
+/// # Implementation and documentation notes
+/// Individual `connect_*` methods are generated using a declarative macro, to support a variadic number of parameters **and** type inference.
+/// Without inference, it is not reliably possible[^rust-issue] to pass `|this, arg| { ... }` closures and would require the more verbose
+/// `|this: &mut MyClass, arg: GString| { ... }` syntax. Unfortunately, this design choice precludes the usage of traits for abstraction over
+/// different functions. There are potential workarounds[^workaround], let us know in case you find a way.
+///
+/// To keep this documentation readable, we only document one overload of each implementation: arbitrarily the one with three parameters
+/// `(P0, P1, P2)`. Keep this in mind when looking at a concrete signature.
+///
+/// [^rust-issue]: See Rust issue [#63702](https://github.com/rust-lang/rust/issues/63702) or
+///   [rust-lang discussion](https://users.rust-lang.org/t/what-are-the-limits-of-type-inference-in-closures/31519).
+/// [^workaround]: Using macros to have one less indirection level is one workaround.
+///   [Identity functions](https://users.rust-lang.org/t/type-inference-in-closures/78399/3) might be another.
 pub struct TypedSignal<'c, C: WithSignals, Ps> {
     /// In Godot, valid signals (unlike funcs) are _always_ declared in a class and become part of each instance. So there's always an object.
     object: C::__SignalObj<'c>,
@@ -162,10 +175,8 @@ impl<'c, C: WithSignals, Ps: meta::ParamTuple> TypedSignal<'c, C, Ps> {
 }
 
 macro_rules! impl_signal_connect {
-    ($( $args:ident : $Ps:ident ),*) => {
-        // --------------------------------------------------------------------------------------------------------------------------------------
-        // SignalReceiver
-
+    ($( #[$attr:meta] )? $( $args:ident : $Ps:ident ),*) => {
+        $( #[$attr] )?
         impl<C: WithSignals, $($Ps: Debug + FromGodot + 'static),*>
             TypedSignal<'_, C, ($($Ps,)*)> {
             /// Connect a non-member function (global function, associated function or closure).
@@ -240,14 +251,14 @@ macro_rules! impl_signal_connect {
     };
 }
 
-impl_signal_connect!();
-impl_signal_connect!(arg0: P0);
-impl_signal_connect!(arg0: P0, arg1: P1);
-impl_signal_connect!(arg0: P0, arg1: P1, arg2: P2);
-impl_signal_connect!(arg0: P0, arg1: P1, arg2: P2, arg3: P3);
-impl_signal_connect!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4);
-impl_signal_connect!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5);
-impl_signal_connect!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6);
-impl_signal_connect!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7);
-impl_signal_connect!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8);
-impl_signal_connect!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8, arg9: P9);
+impl_signal_connect!(#[doc(hidden)] );
+impl_signal_connect!(#[doc(hidden)] arg0: P0);
+impl_signal_connect!(#[doc(hidden)] arg0: P0, arg1: P1);
+impl_signal_connect!(               arg0: P0, arg1: P1, arg2: P2);
+impl_signal_connect!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3);
+impl_signal_connect!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4);
+impl_signal_connect!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5);
+impl_signal_connect!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6);
+impl_signal_connect!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7);
+impl_signal_connect!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8);
+impl_signal_connect!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8, arg9: P9);
