Various doc improvements, mostly around signal + async

Author: Bromeon

godot-core/src/builtin/collections/packed_array.rs

@@ -58,8 +58,7 @@ macro_rules! impl_packed_array {
             $($trait_impls:tt)*
         },
     ) => {
-        #[doc = concat!("Implements Godot's `", stringify!($PackedArray), "` type,")]
-        #[doc = concat!("which is a space-efficient array of `", stringify!($Element), "`s.")]
+        #[doc = concat!("Space-efficient array of [`", stringify!($Element), "`] elements.")]
         ///
         /// Check out the [book](https://godot-rust.github.io/book/godot-api/builtins.html#packed-arrays) for a tutorial on packed arrays.
         ///

godot-core/src/builtin/real.rs

@@ -196,7 +196,7 @@ macro_rules! real {
     }};
 }
 
-/// Array of reals.
+/// Array of [`real`]s.
 ///
 /// The expression has type `[real; N]` where `N` is the number of elements in the array.
 ///

godot-core/src/builtin/signal.rs

@@ -19,12 +19,13 @@ use crate::obj::bounds::DynMemory;
 use crate::obj::{Bounds, Gd, GodotClass, InstanceId};
 use sys::{ffi_methods, GodotFfi};
 
-/// A `Signal` represents a signal of an Object instance in Godot.
+/// Untyped Godot signal.
 ///
-/// Signals are composed of a reference to an `Object` and the name of the signal on this object.
+/// Signals are composed of a pointer to an `Object` and the name of the signal on this object.
 ///
-/// # Godot docs
+/// In Rust, you might want to work with type-safe signals, available under the [`TypedSignal`](crate::registry::signal::TypedSignal) struct.
 ///
+/// # Godot docs
 /// [`Signal` (stable)](https://docs.godotengine.org/en/stable/classes/class_signal.html)
 pub struct Signal {
     opaque: sys::types::OpaqueSignal,
@@ -75,7 +76,7 @@ impl Signal {
     /// A signal can only be connected once to the same [`Callable`]. If the signal is already connected,
     /// returns [`Error::ERR_INVALID_PARAMETER`] and
     /// pushes an error message, unless the signal is connected with [`ConnectFlags::REFERENCE_COUNTED`](crate::classes::object::ConnectFlags::REFERENCE_COUNTED).
-    /// To prevent this, use [`Self::is_connected`] first to check for existing connections.
+    /// To prevent this, check for existing connections with [`is_connected()`][Self::is_connected].
     pub fn connect(&self, callable: &Callable, flags: i64) -> Error {
         let error = self.as_inner().connect(callable, flags);
 
@@ -84,7 +85,7 @@ impl Signal {
 
     /// Disconnects this signal from the specified [`Callable`].
     ///
-    /// If the connection does not exist, generates an error. Use [`Self::is_connected`] to make sure that the connection exists.
+    /// If the connection does not exist, generates an error. Use [`is_connected()`](Self::is_connected) to make sure that the connection exists.
     pub fn disconnect(&self, callable: &Callable) {
         self.as_inner().disconnect(callable);
     }

godot-core/src/builtin/string/gstring.rs

@@ -84,7 +84,7 @@ impl GString {
     ///
     /// Some notes on the encodings:
     /// - **Latin-1:** Since every byte is a valid Latin-1 character, no validation besides the `NUL` byte is performed.
-    ///   It is your responsibility to ensure that the input is valid Latin-1.
+    ///   It is your responsibility to ensure that the input is meaningful under Latin-1.
     /// - **ASCII**: Subset of Latin-1, which is additionally validated to be valid, non-`NUL` ASCII characters.
     /// - **UTF-8**: The input is validated to be UTF-8.
     ///

godot-core/src/builtin/string/string_name.rs

@@ -67,7 +67,7 @@ impl StringName {
     ///
     /// Some notes on the encodings:
     /// - **Latin-1:** Since every byte is a valid Latin-1 character, no validation besides the `NUL` byte is performed.
-    ///   It is your responsibility to ensure that the input is valid Latin-1.
+    ///   It is your responsibility to ensure that the input is meaningful under Latin-1.
     /// - **ASCII**: Subset of Latin-1, which is additionally validated to be valid, non-`NUL` ASCII characters.
     /// - **UTF-8**: The input is validated to be UTF-8.
     ///

godot-core/src/obj/traits.rs

@@ -499,13 +499,21 @@ pub trait WithUserSignals: WithSignals + WithBaseField {
     /// fn damage_taken(&mut self, amount: i32);
     /// ```
     /// ...then you can access the signal as `self.signals().damage_taken()`, which returns an object with the following API:
+    /// ```ignore
+    /// // Connects global or associated function, or a closure.
+    /// fn connect(f: impl FnMut(i32));
+    ///
+    /// // Connects a &mut self method or closure on the emitter object.
+    /// fn connect_self(f: impl FnMut(&mut Self, i32));
     ///
-    /// | Method signature | Description |
-    /// |------------------|-------------|
-    /// | `connect(f: impl FnMut(i32))` | Connects global or associated function, or a closure. |
-    /// | `connect_self(f: impl FnMut(&mut Self, i32))` | Connects a `&mut self` method or closure. |
-    /// | `emit(amount: i32)` | Emits the signal with the given arguments. |
+    /// // Connects a &mut self method or closure on another object.
+    /// fn connect_other<C>(f: impl FnMut(&mut C, i32));
+    ///
+    /// // Emits the signal with the given arguments.
+    /// fn emit(amount: i32);
+    /// ```
     ///
+    /// See [`TypedSignal`](crate::registry::signal::TypedSignal) for more information.
     fn signals(&mut self) -> Self::SignalCollection<'_, Self>;
 }
 

godot-core/src/registry/signal/signal_receiver.rs

@@ -24,23 +24,64 @@ use std::marker::PhantomData;
 /// - `&mut C` for `&mut self` methods.
 ///
 /// See also [Signals](https://godot-rust.github.io/book/register/signals.html) in the book.
+///
+/// # Usage as a bound
+/// To write generic code that handles different functions and forwards them to [`TypedSignal`] and [`ConnectBuilder`] APIs,
+/// you have to use `SignalReceiver` in combination with [`IndirectSignalReceiver`]. Consult the docs of the latter for elaboration.
+///
+/// [`TypedSignal`]: crate::registry::signal::TypedSignal
+/// [`ConnectBuilder`]: crate::registry::signal::ConnectBuilder
+///
+/// # Hidden `impls` in this doc
+/// To keep this documentation readable, we only document one variant of each `impl SignalReceiver`: arbitrarily the one with three parameters
+/// `(P0, P1, P2)`. Keep this in mind when looking at a concrete signature.
 pub trait SignalReceiver<C, Ps>: 'static {
     /// Invoke the receiver on the given instance (possibly `()`) with `params`.
     fn call(&mut self, maybe_instance: C, params: Ps);
 }
 
 // Next-gen trait solver should allow for type inference in closures, when function traits are involved, without using identity struct
 // and other hacks. Since `IndirectSignalReceiver` is just a view, it should be drop-in replacement.
-/// A special "identity struct" which allows to use type inference while specifying various closures for connections.
+/// A special "identity struct" which enables type inference while specifying various closures for connections.
+///
+/// If you want to write generic code that can handle different functions and forward them to [`TypedSignal`] and [`ConnectBuilder`] APIs,
+/// you have to use [`SignalReceiver`] in combination with this type. Please check its documentation for a detailed explanation.
+///
+/// [`TypedSignal`]: crate::registry::signal::TypedSignal
+/// [`ConnectBuilder`]: crate::registry::signal::ConnectBuilder
+///
+/// # Background
+///
+/// Individual `connect*` methods on `TypedSignal` and `ConnectBuilder` use the `SignalReceiver` trait as a bound.  \
+/// **In addition to that**, they have a rather complex bound involving [`IndirectSignalReceiver`]:
+///
+/// ```no_run
+/// # use godot::register::{IndirectSignalReceiver, SignalReceiver};
+/// # use godot_core::meta::InParamTuple;
+/// # use godot_core::obj::WithSignals;
+/// # struct TypedSignal<'c, C: WithSignals, Ps> { _phantom: std::marker::PhantomData<&'c (C, Ps)> }
+/// impl<C: WithSignals, Ps: InParamTuple + 'static> TypedSignal<'_, C, Ps> {
+///     pub fn connect<F>(&self, mut function: F)
+///     where
+///         for<'c_rcv> F: SignalReceiver<(), Ps> + 'static,
+///         for<'c_rcv> IndirectSignalReceiver<'c_rcv, (), Ps, F>: From<&'c_rcv mut F>,
+///     { /* ... */ }
+/// }
+/// ```
 ///
-/// rustc can't infer types in closures when dealing with `Fn/FnMut/FnOnce` traits abstracted behind another trait (in our case
-/// [`SignalReceiver`]). To make type inference work in such cases, we need to specify concrete type – such as `FnMut(...) -> R`
-/// or `<&mut F as Into<IndirectSignalReceiver<'_, Instance, Params, Func>>>`.
+/// This second bound is necessary because rustc cannot infer parameter types in closures, when dealing with `Fn/FnMut/FnOnce` traits abstracted
+/// behind another trait (in our case [`SignalReceiver`]). Without inference, it wouldn't be reliably possible to pass `|this, arg| { ... }`
+/// closures and would require the more verbose `|this: &mut MyClass, arg: GString| { ... }` syntax.
 ///
-/// In other words, `IndirectSignalReceiver` allows us to "smuggle" in a `Fn*` trait, forcing rustc to deal with type inference while resolving
-/// its inner type.
+/// To make type inference work in such cases, we need to specify concrete type, such as `FnMut(...) -> R` or
+/// `<&mut F as Into<IndirectSignalReceiver<'_, MyClass, (Param0, Param1), Func>>>`. The ~~dirty hack~~ clever trick used here is to "smuggle" a
+/// concrete `Fn*` trait through `IndirectSignalReceiver`. This forces rustc to resolve the concrete `Fn*` type.
 ///
-/// # Example usage
+/// Prior designs included declarative macros to generate all `connect*` functions with direct `Fn*` bounds (not through `SignalReceiver`).
+/// This works well, too, but prevents users from extending the functionality through generic programming -- they'd need to use macros, too.
+///
+/// # Usage within `connect*` style methods
+/// When using the trait bounds as described above, you can access the actual function in the following way:
 ///
 /// ```no_run
 /// # use godot::register::{IndirectSignalReceiver, SignalReceiver};
@@ -49,41 +90,55 @@ pub trait SignalReceiver<C, Ps>: 'static {
 /// IndirectSignalReceiver::from(&mut function)
 ///     .function()
 ///     .call((), args);
-///```
+/// ```
+///
+/// # Hidden `impls` in this doc
+/// To keep this documentation readable, we only document one variant of each `impl From<F>`: arbitrarily the one with three parameters
+/// `(P0, P1, P2)`. Keep this in mind when looking at a concrete signature.
 ///
 /// # Further reading
 /// - [rustc issue #63702](https://github.com/rust-lang/rust/issues/63702)
 /// - [identity function trick](https://users.rust-lang.org/t/type-inference-in-closures/78399/3)
+/// - [discussion about type-inference limits](https://users.rust-lang.org/t/what-are-the-limits-of-type-inference-in-closures/31519)
 /// - [rustc comments around closure type-check](https://github.com/rust-lang/rust/blob/5ad7454f7503b6af2800bf4a7c875962cb03f913/compiler/rustc_hir_typeck/src/fn_ctxt/checks.rs#L306-L317)
-pub struct IndirectSignalReceiver<'view, I, Ps, F>
+pub struct IndirectSignalReceiver<'view, C, Ps, F>
 where
     Ps: InParamTuple,
-    F: SignalReceiver<I, Ps> + 'static,
+    F: SignalReceiver<C, Ps> + 'static,
 {
     inner: &'view mut F,
-    _phantoms: PhantomData<(I, Ps)>,
+    _phantoms: PhantomData<(C, Ps)>,
 }
 
-impl<'view, I, Ps, F> IndirectSignalReceiver<'view, I, Ps, F>
+impl<'view, C, Ps, F> IndirectSignalReceiver<'view, C, Ps, F>
 where
     Ps: InParamTuple,
-    F: SignalReceiver<I, Ps> + 'static,
+    F: SignalReceiver<C, Ps> + 'static,
 {
     /// Retrieves inner `&mut F` function ready to be used as [`SignalReceiver`].
     pub fn function(&'view mut self) -> &'view mut F {
         self.inner
     }
+
+    /// Creates a new `IndirectSignalReceiver` from a mutable reference to a function.
+    fn new(inner: &'view mut F) -> Self {
+        Self {
+            inner,
+            _phantoms: PhantomData,
+        }
+    }
 }
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 // Generated impls
 
 macro_rules! impl_signal_recipient {
-    ($( $args:ident : $Ps:ident ),*) => {
+    ($( #[$attr:meta] )? $( $args:ident : $Ps:ident ),*) => {
         // --------------------------------------------------------------------------------------------------------------------------------------
         // SignalReceiver
 
-        // Global and associated functions.
+        // SignalReceiver: Global and associated functions.
+        $( #[$attr] )?
         impl<F, R, $($Ps: std::fmt::Debug + FromGodot + 'static),*> SignalReceiver<(), ( $($Ps,)* )> for F
             where F: FnMut( $($Ps,)* ) -> R + 'static
         {
@@ -92,7 +147,8 @@ macro_rules! impl_signal_recipient {
             }
         }
 
-        // Methods with mutable receiver - &mut self.
+        // SignalReceiver: Methods with mutable receiver - &mut self.
+        $( #[$attr] )?
         impl<F, R, C, $($Ps: std::fmt::Debug + FromGodot + 'static),*> SignalReceiver<&mut C, ( $($Ps,)* )> for F
             where F: FnMut( &mut C, $($Ps,)* ) -> R + 'static
         {
@@ -101,16 +157,20 @@ macro_rules! impl_signal_recipient {
             }
         }
 
-        // Methods with immutable receiver - &self.
+        // Methods with immutable receiver - &self. Disabled until needed.
+        /*
+        $( #[$attr] )?
         impl<F, R, C, $($Ps: std::fmt::Debug + FromGodot + 'static),*> SignalReceiver<&C, ( $($Ps,)* )> for F
             where F: FnMut( &C, $($Ps,)* ) -> R + 'static
         {
             fn call(&mut self, instance: &C, ($($args,)*): ( $($Ps,)* )) {
                 self(instance, $($args,)*);
             }
         }
+        */
 
-        // Methods with gd receiver - Gd<Self>.
+        // Methods with Gd receiver - Gd<Self>.
+        $( #[$attr] )?
         impl<F, R, C, $($Ps: std::fmt::Debug + FromGodot + 'static),*> SignalReceiver<Gd<C>, ( $($Ps,)* )> for F
             where F: FnMut( Gd<C>, $($Ps,)* ) -> R + 'static, C: GodotClass
         {
@@ -119,63 +179,65 @@ macro_rules! impl_signal_recipient {
             }
         }
 
-                // --------------------------------------------------------------------------------------------------------------------------------------
+        // --------------------------------------------------------------------------------------------------------------------------------------
         // FnMut -> IndirectSignalReceiver
 
-        impl<'c_view, F, R, $($Ps: std::fmt::Debug + FromGodot + 'static),*> From<&'c_view mut F> for IndirectSignalReceiver<'c_view, (), ($($Ps,)*), F>
+        // From: Global and associated functions.
+        $( #[$attr] )?
+        impl<'c_view, F, R, $($Ps: std::fmt::Debug + FromGodot + 'static),*>
+            From<&'c_view mut F> for IndirectSignalReceiver<'c_view, (), ($($Ps,)*), F>
             where F: FnMut( $($Ps,)* ) -> R + 'static
         {
             fn from(value: &'c_view mut F) -> Self {
-                IndirectSignalReceiver {
-                    inner: value,
-                    _phantoms: PhantomData,
-                }
+                IndirectSignalReceiver::new(value)
             }
         }
 
-        impl<'c_view, F, R, C, $($Ps: std::fmt::Debug + FromGodot + 'static),*> From<&'c_view mut F> for IndirectSignalReceiver<'c_view, &mut C, ($($Ps,)*), F>
+        // From: Methods with mutable receiver - &mut self.
+        $( #[$attr] )?
+        impl<'c_view, F, R, C, $($Ps: std::fmt::Debug + FromGodot + 'static),*>
+            From<&'c_view mut F> for IndirectSignalReceiver<'c_view, &mut C, ($($Ps,)*), F>
             where F: FnMut( &mut C, $($Ps,)* ) -> R + 'static
         {
             fn from(value: &'c_view mut F) -> Self {
-                IndirectSignalReceiver {
-                    inner: value,
-                    _phantoms: PhantomData,
-                }
+                IndirectSignalReceiver::new(value)
             }
         }
 
-        impl<'c_view, F, R, C, $($Ps: std::fmt::Debug + FromGodot + 'static),*> From<&'c_view mut F> for IndirectSignalReceiver<'c_view, &C, ($($Ps,)*), F>
+        // From: Methods with immutable receiver - &self. Disabled until needed.
+        /*
+        $( #[$attr] )?
+        impl<'c_view, F, R, C, $($Ps: std::fmt::Debug + FromGodot + 'static),*>
+            From<&'c_view mut F> for IndirectSignalReceiver<'c_view, &C, ($($Ps,)*), F>
             where F: FnMut( &C, $($Ps,)* ) -> R + 'static
         {
             fn from(value: &'c_view mut F) -> Self {
-                IndirectSignalReceiver {
-                    inner: value,
-                    _phantoms: PhantomData,
-                }
+                IndirectSignalReceiver::new(value)
             }
         }
+        */
 
-        impl<'c_view, F, R, C, $($Ps: std::fmt::Debug + FromGodot + 'static),*> From<&'c_view mut F> for IndirectSignalReceiver<'c_view, Gd<C>, ($($Ps,)*), F>
+        // From: Methods with Gd receiver - Gd<Self>.
+        $( #[$attr] )?
+        impl<'c_view, F, R, C, $($Ps: std::fmt::Debug + FromGodot + 'static),*>
+            From<&'c_view mut F> for IndirectSignalReceiver<'c_view, Gd<C>, ($($Ps,)*), F>
             where F: FnMut( Gd<C>, $($Ps,)* ) -> R + 'static, C: GodotClass
         {
             fn from(value: &'c_view mut F) -> Self {
-                IndirectSignalReceiver {
-                    inner: value,
-                    _phantoms: PhantomData,
-                }
+                IndirectSignalReceiver::new(value)
             }
         }
     };
 }
 
-impl_signal_recipient!();
-impl_signal_recipient!(arg0: P0);
-impl_signal_recipient!(arg0: P0, arg1: P1);
-impl_signal_recipient!(arg0: P0, arg1: P1, arg2: P2);
-impl_signal_recipient!(arg0: P0, arg1: P1, arg2: P2, arg3: P3);
-impl_signal_recipient!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4);
-impl_signal_recipient!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5);
-impl_signal_recipient!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6);
-impl_signal_recipient!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7);
-impl_signal_recipient!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8);
-impl_signal_recipient!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8, arg9: P9);
+impl_signal_recipient!(#[doc(hidden)] );
+impl_signal_recipient!(#[doc(hidden)] arg0: P0);
+impl_signal_recipient!(#[doc(hidden)] arg0: P0, arg1: P1);
+impl_signal_recipient!(               arg0: P0, arg1: P1, arg2: P2);
+impl_signal_recipient!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3);
+impl_signal_recipient!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4);
+impl_signal_recipient!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5);
+impl_signal_recipient!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6);
+impl_signal_recipient!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7);
+impl_signal_recipient!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8);
+impl_signal_recipient!(#[doc(hidden)] arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8, arg9: P9);