From c2a18d593feeebb63d3c430ad16355da0b7e2ba4 Mon Sep 17 00:00:00 2001 From: Gino Valente Date: Thu, 5 Sep 2024 15:20:28 -0700 Subject: [PATCH] Added module-level docs for function overloading --- crates/bevy_reflect/src/func/mod.rs | 30 +++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/crates/bevy_reflect/src/func/mod.rs b/crates/bevy_reflect/src/func/mod.rs index 15d92cb085..6545849d80 100644 --- a/crates/bevy_reflect/src/func/mod.rs +++ b/crates/bevy_reflect/src/func/mod.rs @@ -94,6 +94,32 @@ //! For other functions that don't conform to one of the above signatures, //! [`DynamicFunction`] and [`DynamicFunctionMut`] can instead be created manually. //! +//! # Generic Functions +//! +//! In Rust, generic functions are [monomophized] by the compiler, +//! which means that a separate copy of the function is generated for each concrete set of type parameters. +//! +//! When converting a generic function to a [`DynamicFunction`] or [`DynamicFunctionMut`], +//! the function must be manually monomorphized with concrete types. +//! In other words, you cannot write `add.into_function()`. +//! Instead, you will need to write `add::.into_function()`. +//! +//! This means that reflected functions cannot be generic themselves. +//! To get around this limitation, you can consider [overloading] your function with multiple concrete types. +//! +//! # Overloading Functions +//! +//! Both [`DynamicFunction`] and [`DynamicFunctionMut`] support [function overloading]. +//! +//! Function overloading allows one function to handle multiple types of arguments. +//! This is useful for simulating generic functions by having an overload for each known concrete type. +//! Additionally, it can also simulate [variadic functions]: functions that can be called with a variable number of arguments. +//! +//! Internally, this works by storing multiple functions in a map, +//! where each function is associated with a specific argument signature. +//! +//! To learn more, see the docs on [`DynamicFunction::with_overload`]. +//! //! # Function Registration //! //! This module also provides a [`FunctionRegistry`] that can be used to register functions and closures @@ -127,6 +153,10 @@ //! [`Reflect`]: crate::Reflect //! [lack of variadic generics]: https://poignardazur.github.io/2024/05/25/report-on-rustnl-variadics/ //! [coherence issues]: https://doc.rust-lang.org/rustc/lints/listing/warn-by-default.html#coherence-leak-check +//! [monomophized]: https://en.wikipedia.org/wiki/Monomorphization +//! [overloading]: #overloading-functions +//! [function overloading]: https://en.wikipedia.org/wiki/Function_overloading +//! [variadic functions]: https://en.wikipedia.org/wiki/Variadic_function pub use args::{ArgError, ArgList, ArgValue}; pub use dynamic_function::*;