From 3ceca652dd5dbab48018ccccaa0c9000e4944bd6 Mon Sep 17 00:00:00 2001 From: Jan Haller Date: Sat, 9 Nov 2024 21:43:37 +0100 Subject: [PATCH] Documentation around meta and its argument conversions --- godot-core/src/meta/args/as_arg.rs | 3 +++ godot-core/src/meta/args/object_arg.rs | 2 ++ godot-core/src/meta/mod.rs | 11 ++++++++++- godot/src/lib.rs | 2 ++ 4 files changed, 17 insertions(+), 1 deletion(-) diff --git a/godot-core/src/meta/args/as_arg.rs b/godot-core/src/meta/args/as_arg.rs index 10fdf83dc..a0e637f03 100644 --- a/godot-core/src/meta/args/as_arg.rs +++ b/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. diff --git a/godot-core/src/meta/args/object_arg.rs b/godot-core/src/meta/args/object_arg.rs index c843c01cc..304bd76db 100644 --- a/godot-core/src/meta/args/object_arg.rs +++ b/godot-core/src/meta/args/object_arg.rs @@ -20,6 +20,8 @@ use std::ptr; /// - [`Option<&Gd>`][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 ///
/// The GDExtension API does not inform about nullability of its function parameters. It is up to you to verify that the arguments you pass diff --git a/godot-core/src/meta/mod.rs b/godot-core/src/meta/mod.rs index 9f197b948..64e8dcf30 100644 --- a/godot-core/src/meta/mod.rs +++ b/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` idiom, which can be used to convert +//! "T-compatible" arguments into `T`. This library specializes this idea with two traits: +//! +//! - [`AsArg`] 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`] is a more specialized version of `AsArg` that is used for object arguments, i.e. `Gd`. mod args; mod array_type_info; diff --git a/godot/src/lib.rs b/godot/src/lib.rs index 62bebfd08..11c2ef316 100644 --- a/godot/src/lib.rs +++ b/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` type. //! * [`tools`], higher-level utilities that extend the generated code, e.g. `load()`. +//! * [`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. //!