Documentation around meta and its argument conversions

Author: Bromeon

godot-core/src/meta/args/as_arg.rs

@@ -19,6 +19,9 @@ use std::ffi::CStr;
 /// - `&T` for by-ref builtins: `GString`, `Array`, `Dictionary`, `Packed*Array`, `Variant`...
 /// - `&str`, `&String` additionally for string types `GString`, `StringName`, `NodePath`.
 ///
+/// See also the [`AsObjectArg`][crate::meta::AsObjectArg] trait which is specialized for object arguments. It may be merged with `AsArg`
+/// in the future.
+///
 /// # 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.

godot-core/src/meta/args/object_arg.rs

@@ -20,6 +20,8 @@ use std::ptr;
 /// - [`Option<&Gd<T>>`][Option], to pass optional objects. `None` is mapped to a null argument.
 /// - [`Gd::null_arg()`], to pass `null` arguments without using `Option`.
 ///
+/// Note that [`AsObjectArg`] is very similar to the more general [`AsArg`][crate::meta::AsArg] trait. The two may be merged in the future.
+///
 /// # Nullability
 /// <div class="warning">
 /// The GDExtension API does not inform about nullability of its function parameters. It is up to you to verify that the arguments you pass

godot-core/src/meta/mod.rs

@@ -5,7 +5,7 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-//! Meta-information about variant types, properties and class names.
+//! Meta-information about Godot types, their properties and conversions between them.
 //!
 //! # Conversions between types
 //!
@@ -33,6 +33,15 @@
 //! Godot classes exist in a hierarchy. In OOP, it is usually possible to represent pointers to derived objects as pointer to their bases.
 //! For conversions between base and derived class objects, you can use `Gd` methods [`cast()`][crate::obj::Gd::cast],
 //! [`try_cast()`][crate::obj::Gd::try_cast] and [`upcast()`][crate::obj::Gd::upcast]. Upcasts are infallible.
+//!
+//! ## Argument conversions
+//!
+//! Rust does not support implicit conversions, however it has something very close: the `impl Into<T>` idiom, which can be used to convert
+//! "T-compatible" arguments into `T`. This library specializes this idea with two traits:
+//!
+//! - [`AsArg<T>`] allows argument conversions from arguments into `T`. This is most interesting in the context of strings (so you can pass
+//!   `&str` to a function expecting `GString`), but is generic to support e.g. array insertion.
+//! - [`AsObjectArg<T>`] is a more specialized version of `AsArg` that is used for object arguments, i.e. `Gd<T>`.
 
 mod args;
 mod array_type_info;

godot/src/lib.rs

@@ -33,6 +33,8 @@
 //! * [`register`], used to register **your own** Rust symbols (classes, methods, constants etc.) with Godot.
 //! * [`obj`], everything related to handling Godot objects, such as the `Gd<T>` type.
 //! * [`tools`], higher-level utilities that extend the generated code, e.g. `load<T>()`.
+//! * [`meta`], fundamental information about types, properties and conversions.
+//! * [`init`], entry point and global library configuration.
 //!
 //! The [`prelude`] contains often-imported symbols; feel free to `use godot::prelude::*` in your code.
 //! <br><br>