Docs + naming

Author: Bromeon

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

@@ -12,7 +12,7 @@ use crate::builtin::*;
 use crate::meta;
 use crate::meta::error::{ConvertError, FromGodotError, FromVariantError};
 use crate::meta::{
-    ArgTarget, ArrayElement, ArrayTypeInfo, AsArg, CowArg, FromGodot, GodotConvert,
+    ArrayElement, ArrayTypeInfo, AsArg, CowArg, DeclParam, FromGodot, GodotConvert,
     GodotFfiVariant, GodotType, PropertyHintInfo, RefArg, ToGodot,
 };
 use crate::registry::property::{Export, Var};
@@ -944,14 +944,14 @@ impl<'r, T: ArrayElement> AsArg<Array<T>> for &'r Array<T> {
     }
 }
 
-impl<T: ArrayElement> ArgTarget for Array<T> {
-    type Type<'v> = CowArg<'v, Self>;
+impl<T: ArrayElement> DeclParam for Array<T> {
+    type Arg<'v> = CowArg<'v, Self>;
 
-    fn value_to_arg<'v>(self) -> Self::Type<'v> {
+    fn value_to_arg<'v>(self) -> Self::Arg<'v> {
         CowArg::Owned(self)
     }
 
-    fn arg_to_ref<'r>(arg: &'r Self::Type<'_>) -> &'r Self {
+    fn arg_to_ref<'r>(arg: &'r Self::Arg<'_>) -> &'r Self {
         arg.cow_as_ref()
     }
 }
@@ -1221,7 +1221,7 @@ impl<T: ArrayElement + ToGodot> Extend<T> for Array<T> {
         // A faster implementation using `resize()` and direct pointer writes might still be possible.
         // Note that this could technically also use iter(), since no moves need to happen (however Extend requires IntoIterator).
         for item in iter.into_iter() {
-            self.push(ArgTarget::value_to_arg(item));
+            self.push(DeclParam::value_to_arg(item));
         }
     }
 }

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

@@ -8,7 +8,7 @@
 use godot_ffi as sys;
 
 use crate::builtin::*;
-use crate::meta::{Arg, AsArg, ToGodot};
+use crate::meta::{AsArg, ToGodot};
 use std::{fmt, ops, ptr};
 use sys::types::*;
 use sys::{ffi_methods, interface_fn, GodotFfi};
@@ -107,7 +107,7 @@ macro_rules! impl_packed_array {
             }
 
             /// Returns the number of times a value is in the array.
-            pub fn count(&self, value: Arg<$Element>) -> usize {
+            pub fn count(&self, value: impl AsArg<$Element>) -> usize {
                 to_usize(self.as_inner().count(value.into_arg().into_packed_arg()))
             }
 
@@ -140,7 +140,7 @@ macro_rules! impl_packed_array {
             /// Note: On large arrays, this method is much slower than `push` as it will move all
             /// the array's elements after the inserted element. The larger the array, the slower
             /// `insert` will be.
-            pub fn insert(&mut self, index: usize, value: Arg<$Element>) {
+            pub fn insert(&mut self, index: usize, value: impl AsArg<$Element>) {
                 // Intentional > and not >=.
                 if index > self.len() {
                     self.panic_out_of_bounds(index);
@@ -170,7 +170,7 @@ macro_rules! impl_packed_array {
 
             /// Assigns the given value to all elements in the array. This can be used together
             /// with `resize` to create an array with a given size and initialized elements.
-            pub fn fill(&mut self, value: Arg<$Element>) {
+            pub fn fill(&mut self, value: impl AsArg<$Element>) {
                 self.as_inner().fill(value.into_arg().into_packed_arg());
             }
 
@@ -262,7 +262,7 @@ macro_rules! impl_packed_array {
             /// Searches the array for the first occurrence of a value and returns its index, or
             /// `None` if not found. Starts searching at index `from`; pass `None` to search the
             /// entire array.
-            pub fn find(&self, value: Arg<$Element>, from: Option<usize>) -> Option<usize> {
+            pub fn find(&self, value: impl AsArg<$Element>, from: Option<usize>) -> Option<usize> {
                 let from = to_i64(from.unwrap_or(0));
                 let index = self.as_inner().find(value.into_arg().into_packed_arg(), from);
                 if index >= 0 {
@@ -275,7 +275,7 @@ macro_rules! impl_packed_array {
             /// Searches the array backwards for the last occurrence of a value and returns its
             /// index, or `None` if not found. Starts searching at index `from`; pass `None` to
             /// search the entire array.
-            pub fn rfind(&self, value: Arg<$Element>, from: Option<usize>) -> Option<usize> {
+            pub fn rfind(&self, value: impl AsArg<$Element>, from: Option<usize>) -> Option<usize> {
                 let from = from.map(to_i64).unwrap_or(-1);
                 let index = self.as_inner().rfind(value.into_arg().into_packed_arg(), from);
                 // It's not documented, but `rfind` returns -1 if not found.
@@ -291,7 +291,7 @@ macro_rules! impl_packed_array {
             /// If the value is not present in the array, returns the insertion index that would maintain sorting order.
             ///
             /// Calling `bsearch()` on an unsorted array results in unspecified (but safe) behavior.
-            pub fn bsearch(&self, value: Arg<$Element>) -> usize {
+            pub fn bsearch(&self, value: impl AsArg<$Element>) -> usize {
                 to_usize(self.as_inner().bsearch(value.into_arg().into_packed_arg(), true))
             }
 
@@ -491,7 +491,7 @@ macro_rules! impl_packed_array {
                 // A faster implementation using `resize()` and direct pointer writes might still be
                 // possible.
                 for item in iter.into_iter() {
-                    self.push(meta::ArgTarget::value_to_arg(item));
+                    self.push(meta::DeclParam::value_to_arg(item));
                 }
             }
         }

godot-core/src/meta/as_arg.rs

@@ -14,27 +14,41 @@ use std::ffi::CStr;
 /// An `impl AsArg<T>` parameter allows values to be passed which can be represented in the target type `T`. Note that unlike `From<T>`,
 /// this trait is implemented more conservatively.
 ///
+/// As a result, `AsArg<T>` is currently only implemented for certain argument types:
+/// - `T` for by-value builtins (typically `Copy`): `i32`, `bool`, `Vector3`, `Transform2D`, ...
+/// - `&T` for by-ref builtins: `GString`, `Array`, `Dictionary`, `Packed*Array`, `Variant`...
+/// - `&str`, `&String` additionally for string types `GString`, `StringName`, `NodePath`.
+///
+/// # Pass by value
+/// Implicitly converting from `T` for by-ref builtins is explicitly not supported. This emphasizes that there is no need to consume the object,
+/// thus discourages unnecessary cloning.
+///
+/// If you need to pass owned values in generic code, you can use [`DeclParam::value_to_arg()`].
+///
 /// # Performance for strings
 /// Godot has three string types: [`GString`], [`StringName`] and [`NodePath`]. Conversions between those three, as well as between `String` and
 /// them, is generally expensive because of allocations, re-encoding, validations, hashing, etc. While this doesn't matter for a few strings
 /// passed to engine APIs, it can become a problematic when passing long strings in a hot loop.
 ///
-/// As a result, `AsArg<T>` is currently only implemented for certain conversions:
-/// - `&T` and `&mut T`, since those require no conversion or copy.
-/// - String literals like `"string"` and `c"string"`. While these _do_ need conversions, those are quite explicit, and
-///   `&'static CStr -> StringName` in particular is cheap.
+/// In the case of strings, we allow implicit conversion from Rust types `&str`, `&String` and `&'static CStr` (`StringName` only).
+/// While these conversions are not free, those are either explicit because a string literal is used, or they are unsurprising, because Godot
+/// cannot deal with raw Rust types. On the other hand, `GString` and `StringName` are sometimes used almost interchangeably (example:
+/// [`Node::set_name`](crate::classes::Node::set_name) takes `GString` but [`Node::get_name`](crate::classes::Node::get_name) returns `StringName`).
+///
+/// If you want to convert between Godot's string types for the sake of argument passing, each type provides an `arg()` method, such as
+/// [`GString::arg()`]. You cannot use this method in other contexts.
 #[diagnostic::on_unimplemented(
     message = "Argument of type `{Self}` cannot be passed to an `impl AsArg<{T}>` parameter",
     note = "If you pass by value, consider borrowing instead.",
     note = "GString/StringName/NodePath aren't implicitly convertible for performance reasons; use their `arg()` method.",
     note = "See also `AsArg` docs: https://godot-rust.github.io/docs/gdext/master/godot/meta/trait.AsArg.html"
 )]
-pub trait AsArg<T: ArgTarget>
+pub trait AsArg<T: DeclParam>
 where
     Self: Sized,
 {
     #[doc(hidden)]
-    fn into_arg<'r>(self) -> <T as ArgTarget>::Type<'r>
+    fn into_arg<'r>(self) -> <T as DeclParam>::Arg<'r>
     where
         Self: 'r;
 }
@@ -56,7 +70,7 @@ macro_rules! arg_into_ref {
     };
     ($arg_variable:ident: $T:ty) => {
         let $arg_variable = $arg_variable.into_arg();
-        let $arg_variable: &$T = $crate::meta::ArgTarget::arg_to_ref(&$arg_variable);
+        let $arg_variable: &$T = $crate::meta::DeclParam::arg_to_ref(&$arg_variable);
     };
 }
 
@@ -76,20 +90,20 @@ macro_rules! arg_into_owned {
 macro_rules! impl_asarg_by_value {
     ($T:ty) => {
         impl $crate::meta::AsArg<$T> for $T {
-            fn into_arg<'r>(self) -> <$T as $crate::meta::ArgTarget>::Type<'r> {
+            fn into_arg<'r>(self) -> <$T as $crate::meta::DeclParam>::Arg<'r> {
                 // Moves value (but typically a Copy type).
                 self
             }
         }
 
-        impl $crate::meta::ArgTarget for $T {
-            type Type<'v> = $T;
+        impl $crate::meta::DeclParam for $T {
+            type Arg<'v> = $T;
 
-            fn value_to_arg<'v>(self) -> Self::Type<'v> {
+            fn value_to_arg<'v>(self) -> Self::Arg<'v> {
                 self
             }
 
-            fn arg_to_ref<'r>(arg: &'r Self::Type<'_>) -> &'r Self {
+            fn arg_to_ref<'r>(arg: &'r Self::Arg<'_>) -> &'r Self {
                 arg
             }
         }
@@ -107,22 +121,22 @@ macro_rules! impl_asarg_by_ref {
             // Thus, keep `where` on same line.
             // type ArgType<'v> = &'v $T where Self: 'v;
 
-            fn into_arg<'cow>(self) -> <$T as $crate::meta::ArgTarget>::Type<'cow>
+            fn into_arg<'cow>(self) -> <$T as $crate::meta::DeclParam>::Arg<'cow>
             where
                 'r: 'cow, // Original reference must be valid for at least as long as the returned cow.
             {
                 $crate::meta::CowArg::Borrowed(self)
             }
         }
 
-        impl $crate::meta::ArgTarget for $T {
-            type Type<'v> = $crate::meta::CowArg<'v, $T>;
+        impl $crate::meta::DeclParam for $T {
+            type Arg<'v> = $crate::meta::CowArg<'v, $T>;
 
-            fn value_to_arg<'v>(self) -> Self::Type<'v> {
+            fn value_to_arg<'v>(self) -> Self::Arg<'v> {
                 $crate::meta::CowArg::Owned(self)
             }
 
-            fn arg_to_ref<'r>(arg: &'r Self::Type<'_>) -> &'r Self {
+            fn arg_to_ref<'r>(arg: &'r Self::Arg<'_>) -> &'r Self {
                 arg.cow_as_ref()
             }
         }
@@ -136,11 +150,11 @@ macro_rules! declare_arg_method {
         ///
         /// # Generic bounds
         /// The bounds are implementation-defined and may change at any time. Do not use this function in a generic context requiring `T`
-        /// -- use the `From` trait in that case.
+        /// -- use the `From` trait or [`DeclParam`][crate::meta::DeclParam] in that case.
         pub fn arg<T>(&self) -> impl $crate::meta::AsArg<T>
         where
             for<'a> T: From<&'a Self>
-                + $crate::meta::ArgTarget<Type<'a> = $crate::meta::CowArg<'a, T>>
+                + $crate::meta::DeclParam<Arg<'a> = $crate::meta::CowArg<'a, T>>
                 + 'a,
         {
             $crate::meta::CowArg::Owned(T::from(self))
@@ -157,7 +171,7 @@ macro_rules! declare_arg_method {
 /// This is necessary for packed array dispatching to different "inner" backend signatures.
 impl<'a, T> AsArg<T> for CowArg<'a, T>
 where
-    for<'r> T: ArgTarget<Type<'r> = CowArg<'r, T>> + 'r,
+    for<'r> T: DeclParam<Arg<'r> = CowArg<'r, T>> + 'r,
 {
     fn into_arg<'r>(self) -> CowArg<'r, T>
     where
@@ -228,32 +242,28 @@ impl AsArg<NodePath> for &String {
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
-/// Implemented for all types that can be stored in [`AsArg<T>`].
-pub trait ArgTarget
+/// Implemented for all parameter types `T` that are allowed to receive [impl `AsArg<T>`][AsArg]`.
+pub trait DeclParam
 where
     Self: Sized,
 {
-    /// Target type, either `T` or `CowArg<'v, T>`.
+    /// Canonical argument passing type, either `T` or an internally-used CoW type.
     ///
     /// The general rule is that `Copy` types are passed by value, while the rest is passed by reference.
     ///
-    /// This associated type is closely related to [`ToGodot::ToVia<'v>`] and may be reorganized.
-    type Type<'v>: AsArg<Self>
+    /// This associated type is closely related to [`ToGodot::ToVia<'v>`][crate::meta::ToGodot::ToVia] and may be reorganized.
+    type Arg<'v>: AsArg<Self>
     where
         Self: 'v;
 
-    /// Converts an owned value to the canonical argument type.
+    /// Converts an owned value to the canonical argument type, which can be passed to [`impl AsArg<T>`][AsArg].
     ///
     /// Useful in generic contexts where only a value is available, and one doesn't want to dispatch between value/reference.
-    #[doc(hidden)]
-    fn value_to_arg<'v>(self) -> Self::Type<'v>;
+    fn value_to_arg<'v>(self) -> Self::Arg<'v>;
 
-    /// Converts an owned value to the canonical argument type.
+    /// Converts an argument to a shared reference.
     ///
-    /// Useful in generic contexts where only a value is available, and one doesn't want to dispatch between value/reference.
-    #[doc(hidden)]
-    fn arg_to_ref<'r>(arg: &'r Self::Type<'_>) -> &'r Self;
+    /// Useful in generic contexts where you need to extract a reference of an argument, independently of how it is passed.
+    #[doc(hidden)] // for now, users are encouraged to use only call-site of impl AsArg; declaration-site may still develop.
+    fn arg_to_ref<'r>(arg: &'r Self::Arg<'_>) -> &'r Self;
 }
-
-/// Shorthand to determine how a type is passed as an argument to Godot APIs.
-pub type Arg<'r, T> = <T as ArgTarget>::Type<'r>;

godot-core/src/meta/cow_arg.rs

@@ -47,7 +47,7 @@ impl<'r, T> CowArg<'r, T> {
     }
 }
 
-/// Exists for polymorphism in [`crate::meta::ArgTarget`].
+/// Exists for polymorphism in [`crate::meta::DeclParam`].
 ///
 /// Necessary for generics in e.g. `Array<T>`, when accepting `impl AsArg<T>` parameters.
 ///

godot-core/src/meta/traits.rs

@@ -162,7 +162,7 @@ pub trait GodotType: GodotConvert<Via = Self> + sealed::Sealed + Sized + 'static
     message = "`Array<T>` can only store element types supported in Godot arrays (no nesting).",
     label = "has invalid element type"
 )]
-pub trait ArrayElement: GodotType + ToGodot + FromGodot + sealed::Sealed + meta::ArgTarget {
+pub trait ArrayElement: GodotType + ToGodot + FromGodot + sealed::Sealed + meta::DeclParam {
     /// Returns the representation of this type as a type string.
     ///
     /// Used for elements in arrays (the latter despite `ArrayElement` not having a direct relation).

godot-core/src/obj/gd.rs

@@ -16,7 +16,7 @@ use crate::builtin::{Callable, NodePath, StringName, Variant};
 use crate::global::PropertyHint;
 use crate::meta::error::{ConvertError, FromFfiError};
 use crate::meta::{
-    ArgTarget, ArrayElement, AsArg, CallContext, ClassName, CowArg, FromGodot, GodotConvert,
+    ArrayElement, AsArg, CallContext, ClassName, CowArg, DeclParam, FromGodot, GodotConvert,
     GodotType, PropertyHintInfo, RefArg, ToGodot,
 };
 use crate::obj::{
@@ -781,14 +781,14 @@ impl<'r, T: GodotClass> AsArg<Gd<T>> for &'r Gd<T> {
     }
 }
 
-impl<T: GodotClass> ArgTarget for Gd<T> {
-    type Type<'v> = CowArg<'v, Gd<T>>;
+impl<T: GodotClass> DeclParam for Gd<T> {
+    type Arg<'v> = CowArg<'v, Gd<T>>;
 
-    fn value_to_arg<'v>(self) -> Self::Type<'v> {
+    fn value_to_arg<'v>(self) -> Self::Arg<'v> {
         CowArg::Owned(self)
     }
 
-    fn arg_to_ref<'r>(arg: &'r Self::Type<'_>) -> &'r Self {
+    fn arg_to_ref<'r>(arg: &'r Self::Arg<'_>) -> &'r Self {
         arg.cow_as_ref()
     }
 }
@@ -803,14 +803,14 @@ impl<'r, T: GodotClass> AsArg<Option<Gd<T>>> for Option<&'r Gd<T>> {
     }
 }
 
-impl<T: GodotClass> ArgTarget for Option<Gd<T>> {
-    type Type<'v> = CowArg<'v, Option<Gd<T>>>;
+impl<T: GodotClass> DeclParam for Option<Gd<T>> {
+    type Arg<'v> = CowArg<'v, Option<Gd<T>>>;
 
-    fn value_to_arg<'v>(self) -> Self::Type<'v> {
+    fn value_to_arg<'v>(self) -> Self::Arg<'v> {
         CowArg::Owned(self)
     }
 
-    fn arg_to_ref<'r>(arg: &'r Self::Type<'_>) -> &'r Self {
+    fn arg_to_ref<'r>(arg: &'r Self::Arg<'_>) -> &'r Self {
         arg.cow_as_ref()
     }
 }