Godot conversion traits: separate public/private API, slightly improve docs

Rename files: godot_compatible -> godot_convert

Author: Bromeon

godot-core/src/builtin/meta/godot_compatible/impls.rs renamed to godot-core/src/builtin/meta/godot_convert/impls.rs

@@ -10,13 +10,15 @@ use crate::builtin::{Variant, VariantConversionError};
 
 use super::{GodotFfiVariant, GodotType};
 
-/// Indicates that a type has some canonical Godot type that can represent it.
+/// Indicates that a type can be passed to/from Godot, either directly or through an intermediate "via" type.
 ///
-/// The type specified here is what will be used to pass this type across to ffi-boundary to/from Godot.
-/// Generally [`ToGodot`] needs to be implemented to pass a type to Godot, and [`FromGodot`] to receive this
-/// type from Godot.
+/// The associated type `Via` specifies _how_ this type is passed across the FFI boundary to/from Godot.
+/// Generally [`ToGodot`] needs to be implemented to pass a type to Godot, and [`FromGodot`] to receive this type from Godot.
+///
+/// [`GodotType`] is a stronger bound than [`GodotConvert`], since it expresses that a type is _directly_ representable
+/// in Godot (without intermediate "via"). Every `GodotType` also implements `GodotConvert` with `Via = Self`.
 pub trait GodotConvert {
-    /// The type used for ffi-passing.
+    /// The type through which `Self` is represented in Godot.
     type Via: GodotType;
 }
 
@@ -33,8 +35,7 @@ pub trait ToGodot: Sized + GodotConvert {
 
     /// Converts this type to the Godot type.
     ///
-    /// This can in some cases enable some optimizations, such as avoiding reference counting for
-    /// reference-counted values.
+    /// This can in some cases enable minor optimizations, such as avoiding reference counting operations.
     fn into_godot(self) -> Self::Via {
         self.to_godot()
     }

godot-core/src/builtin/meta/godot_compatible/mod.rs renamed to godot-core/src/builtin/meta/godot_convert/mod.rs

@@ -7,12 +7,12 @@
 pub mod registration;
 
 mod class_name;
-mod godot_compatible;
+mod godot_convert;
 mod return_marshal;
 mod signature;
 
 pub use class_name::*;
-pub use godot_compatible::*;
+pub use godot_convert::*;
 #[doc(hidden)]
 pub use return_marshal::*;
 #[doc(hidden)]
@@ -25,7 +25,8 @@ use crate::builtin::*;
 use crate::engine::global;
 use registration::method::MethodParamOrReturnInfo;
 
-/// Conversion of GodotFfi-types into/from [`Variant`].
+/// Conversion of [`GodotFfi`] types to/from [`Variant`].
+#[doc(hidden)]
 pub trait GodotFfiVariant: Sized + GodotFfi {
     fn ffi_to_variant(&self) -> Variant;
     fn ffi_from_variant(variant: &Variant) -> Result<Self, VariantConversionError>;
@@ -98,38 +99,48 @@ mod sealed {
     }
 }
 
-/// Types that can represent some Godot type.
-///
-/// This trait cannot be implemented for custom user types, for that you should see [`GodotConvert`]
-/// instead. A type implements `GodotType` when it can directly represent some primitive type exposed by
-/// Godot. For instance, [`i64`] implements `GodotType`, since it can be directly represented by Godot's
-/// `int` type. But [`VariantType`] does not implement `GodotType`. Since while it is an enum Godot uses, we
-/// have no native way to indicate to Godot that a value should be one of the variants of `VariantType`.
+/// Type that is directly representable in the engine.
 ///
-/// Unlike [`GodotFfi`], types implementing this trait don't need to fully represent its corresponding Godot
-/// type. For instance [`i32`] does not implement [`GodotFfi`] because it cannot represent all values of
-/// Godot's `int` type, however it does implement `GodotType` because we can set the metadata of values with
-/// this type to indicate that they are 32 bits large.
+/// This trait cannot be implemented for custom user types; for those, [`GodotConvert`] exists instead.
+/// A type implements `GodotType` when Godot has a direct, native representation for it. For instance:
+/// - [`i64`] implements `GodotType`, since it can be directly represented by Godot's `int` type.
+/// - But [`VariantType`] does not implement `GodotType`. While it is an enum Godot uses, we have no native way to indicate
+///   to Godot that a value should be one of the variants of `VariantType`.
+//
+// Unlike `GodotFfi`, types implementing this trait don't need to fully represent its corresponding Godot
+// type. For instance [`i32`] does not implement `GodotFfi` because it cannot represent all values of
+// Godot's `int` type, however it does implement `GodotType` because we can set the metadata of values with
+// this type to indicate that they are 32 bits large.
 pub trait GodotType: GodotConvert<Via = Self> + ToGodot + FromGodot + sealed::Sealed {
+    #[doc(hidden)]
     type Ffi: GodotFfiVariant;
 
+    #[doc(hidden)]
     fn to_ffi(&self) -> Self::Ffi;
+
+    #[doc(hidden)]
     fn into_ffi(self) -> Self::Ffi;
+
+    #[doc(hidden)]
     fn try_from_ffi(ffi: Self::Ffi) -> Option<Self>;
 
+    #[doc(hidden)]
     fn from_ffi(ffi: Self::Ffi) -> Self {
         Self::try_from_ffi(ffi).unwrap()
     }
 
+    #[doc(hidden)]
     fn param_metadata() -> sys::GDExtensionClassMethodArgumentMetadata {
         Self::Ffi::default_param_metadata()
     }
 
+    #[doc(hidden)]
     fn class_name() -> ClassName {
         // If we use `ClassName::of::<()>()` then this type shows up as `(no base)` in documentation.
         ClassName::none()
     }
 
+    #[doc(hidden)]
     fn property_info(property_name: &str) -> PropertyInfo {
         PropertyInfo {
             variant_type: Self::Ffi::variant_type(),
@@ -141,10 +152,12 @@ pub trait GodotType: GodotConvert<Via = Self> + ToGodot + FromGodot + sealed::Se
         }
     }
 
+    #[doc(hidden)]
     fn argument_info(property_name: &str) -> MethodParamOrReturnInfo {
         MethodParamOrReturnInfo::new(Self::property_info(property_name), Self::param_metadata())
     }
 
+    #[doc(hidden)]
     fn return_info() -> Option<MethodParamOrReturnInfo> {
         Some(MethodParamOrReturnInfo::new(
             Self::property_info(""),

godot-core/src/builtin/meta/mod.rs

@@ -19,6 +19,7 @@ pub trait PtrcallReturn {
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
+#[doc(hidden)]
 pub struct PtrcallReturnOptionGdT<R> {
     _marker: std::marker::PhantomData<R>,
 }
@@ -33,6 +34,7 @@ impl<T: GodotClass> PtrcallReturn for PtrcallReturnOptionGdT<Gd<T>> {
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
+#[doc(hidden)]
 pub struct PtrcallReturnT<R> {
     _marker: std::marker::PhantomData<R>,
 }
@@ -53,6 +55,7 @@ impl<T: FromGodot> PtrcallReturn for PtrcallReturnT<T> {
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
+#[doc(hidden)]
 pub enum PtrcallReturnUnit {}
 
 impl PtrcallReturn for PtrcallReturnUnit {

godot-core/src/builtin/meta/return_marshal.rs

@@ -11,7 +11,7 @@ use venial::Declaration;
 use crate::util::{decl_get_info, DeclInfo};
 use crate::ParseResult;
 
-pub fn derive_godot_compatible(decl: Declaration) -> ParseResult<TokenStream> {
+pub fn derive_godot_convert(decl: Declaration) -> ParseResult<TokenStream> {
     let DeclInfo {
         where_,
         generic_params,

godot-macros/src/derive/derive_godot_compatible.rs renamed to godot-macros/src/derive/derive_godot_convert.rs

@@ -8,12 +8,12 @@
 
 mod derive_export;
 mod derive_from_variant;
-mod derive_godot_compatible;
+mod derive_godot_convert;
 mod derive_property;
 mod derive_to_variant;
 
 pub(crate) use derive_export::*;
 pub(crate) use derive_from_variant::*;
-pub(crate) use derive_godot_compatible::*;
+pub(crate) use derive_godot_convert::*;
 pub(crate) use derive_property::*;
 pub(crate) use derive_to_variant::*;

godot-macros/src/derive/mod.rs

@@ -443,8 +443,8 @@ pub fn godot_api(_meta: TokenStream, input: TokenStream) -> TokenStream {
 }
 
 #[proc_macro_derive(GodotConvert)]
-pub fn derive_godot_compatible(input: TokenStream) -> TokenStream {
-    translate(input, derive::derive_godot_compatible)
+pub fn derive_godot_convert(input: TokenStream) -> TokenStream {
+    translate(input, derive::derive_godot_convert)
 }
 
 /// Derive macro for [ToGodot](../builtin/meta/trait.ToGodot.html) on structs or enums.