- Document stuff

- Seal `GodotType`

Author: lilizoey

godot-core/src/builtin/meta/godot_compat/impls.rs

@@ -34,7 +34,7 @@ where
 {
     fn try_from_godot(via: Self::Via) -> Option<Self> {
         match via {
-            Some(via) => return T::try_from_godot(via).map(Some),
+            Some(via) => T::try_from_godot(via).map(Some),
             None => Some(None),
         }
     }

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

@@ -12,36 +12,69 @@ use crate::builtin::{Variant, VariantConversionError};
 
 use super::{GodotFfiVariant, GodotType};
 
+/// Indicates that a type has some canonical Godot type that can represent it.
+///
+/// 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.
 pub trait GodotCompatible {
+    /// The type used for ffi-passing.
     type Via: GodotType;
 }
 
+/// Defines the canonical conversion to Godot for a type.
+///
+/// It is assumed that all the methods return equal values given equal inputs. Additionally it is assumed
+/// that if [`FromGodot`] is implemented, converting to Godot and back again will return a value equal to the
+/// starting value.
+///
+/// Violating these assumptions is safe but will give unexpected results.
 pub trait ToGodot: Sized + GodotCompatible {
+    /// Converts this type to the Godot type by reference, usually by cloning.
     fn to_godot(&self) -> Self::Via;
 
+    /// Converts this type to the Godot type.
     fn into_godot(self) -> Self::Via {
         self.to_godot()
     }
 
+    /// Converts this type to a [Variant].
     fn to_variant(&self) -> Variant {
         self.to_godot().to_ffi().ffi_to_variant()
     }
 }
 
+/// Defines the canonical conversion from Godot for a type.
+///
+/// It is assumed that all the methods return equal values given equal inputs. Additionally it is assumed
+/// that if [`ToGodot`] is implemented, converting to Godot and back again will return a value equal to the
+/// starting value.
+///
+/// Violating these assumptions is safe but will give unexpected results.
 pub trait FromGodot: Sized + GodotCompatible {
     // TODO: better error
+    /// Performs the conversion.
     fn try_from_godot(via: Self::Via) -> Option<Self>;
 
+    /// ⚠️ Performs the conversion.
+    ///
+    /// # Panics
+    /// If the conversion fails.
     fn from_godot(via: Self::Via) -> Self {
         Self::try_from_godot(via).unwrap()
     }
 
+    /// Performs the conversion from a [`Variant`].
     fn try_from_variant(variant: &Variant) -> Result<Self, VariantConversionError> {
         let ffi = <Self::Via as GodotType>::Ffi::ffi_from_variant(variant)?;
         let via = Self::Via::try_from_ffi(ffi).ok_or(VariantConversionError::BadValue)?;
         Self::try_from_godot(via).ok_or(VariantConversionError::BadValue)
     }
 
+    /// ⚠️ Performs the conversion from a [`Variant`].
+    ///
+    /// # Panics
+    /// If the conversion fails.
     fn from_variant(variant: &Variant) -> Self {
         Self::try_from_variant(variant).unwrap()
     }

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

@@ -25,12 +25,89 @@ use crate::builtin::*;
 use crate::engine::global;
 use registration::method::MethodParamOrReturnInfo;
 
+/// Conversion of GodotFfi-types into/from [`Variant`].
 pub trait GodotFfiVariant: Sized + GodotFfi {
     fn ffi_to_variant(&self) -> Variant;
     fn ffi_from_variant(variant: &Variant) -> Result<Self, VariantConversionError>;
 }
 
-pub trait GodotType: GodotCompatible<Via = Self> + ToGodot + FromGodot {
+mod sealed {
+    // To ensure the user does not implement `GodotType` for their own types.
+
+    use godot_ffi::GodotNullableFfi;
+
+    use super::GodotType;
+    use crate::builtin::*;
+    use crate::obj::*;
+
+    pub trait Sealed {}
+
+    impl Sealed for Aabb {}
+    impl Sealed for Basis {}
+    impl Sealed for Callable {}
+    impl Sealed for Vector2 {}
+    impl Sealed for Vector3 {}
+    impl Sealed for Vector4 {}
+    impl Sealed for Vector2i {}
+    impl Sealed for Vector3i {}
+    impl Sealed for Vector4i {}
+    impl Sealed for Quaternion {}
+    impl Sealed for Color {}
+    impl Sealed for GodotString {}
+    impl Sealed for StringName {}
+    impl Sealed for NodePath {}
+    impl Sealed for PackedByteArray {}
+    impl Sealed for PackedInt32Array {}
+    impl Sealed for PackedInt64Array {}
+    impl Sealed for PackedFloat32Array {}
+    impl Sealed for PackedFloat64Array {}
+    impl Sealed for PackedStringArray {}
+    impl Sealed for PackedVector2Array {}
+    impl Sealed for PackedVector3Array {}
+    impl Sealed for PackedColorArray {}
+    impl Sealed for Plane {}
+    impl Sealed for Projection {}
+    impl Sealed for Rid {}
+    impl Sealed for Rect2 {}
+    impl Sealed for Rect2i {}
+    impl Sealed for Signal {}
+    impl Sealed for Transform2D {}
+    impl Sealed for Transform3D {}
+    impl Sealed for Dictionary {}
+    impl Sealed for bool {}
+    impl Sealed for i64 {}
+    impl Sealed for i32 {}
+    impl Sealed for i16 {}
+    impl Sealed for i8 {}
+    impl Sealed for u64 {}
+    impl Sealed for u32 {}
+    impl Sealed for u16 {}
+    impl Sealed for u8 {}
+    impl Sealed for f64 {}
+    impl Sealed for f32 {}
+    impl Sealed for () {}
+    impl Sealed for Variant {}
+    impl<T: GodotType> Sealed for Array<T> {}
+    impl<T: GodotClass> Sealed for RawGd<T> {}
+    impl<T: GodotClass> Sealed for Gd<T> {}
+    impl<T> Sealed for Option<T>
+    where
+        T: GodotType,
+        T::Ffi: GodotNullableFfi,
+    {
+    }
+}
+
+/// Types that can represent some Godot type.
+///
+/// This trait cannot be implemented for custom user types, for that you should see [`GodotCompatible`]
+/// instead.
+///
+/// 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: GodotCompatible<Via = Self> + ToGodot + FromGodot + sealed::Sealed {
     type Ffi: GodotFfiVariant;
 
     fn to_ffi(&self) -> Self::Ffi;

godot-core/src/obj/raw.rs

@@ -449,7 +449,7 @@ where
     }
 }
 
-unsafe impl<T: GodotClass> GodotNullableFfi for RawGd<T> {
+impl<T: GodotClass> GodotNullableFfi for RawGd<T> {
     fn flatten_option(opt: Option<Self>) -> Self {
         match opt {
             Some(raw) => raw,

godot-ffi/src/godot_ffi.rs

@@ -7,6 +7,8 @@
 use crate as sys;
 use std::marker::PhantomData;
 
+/// Types that can directly and fully represent some Godot type.
+///
 /// Adds methods to convert from and to Godot FFI pointers.
 /// See [crate::ffi_methods] for ergonomic implementation.
 ///
@@ -132,7 +134,10 @@ pub unsafe fn from_sys_init_or_init_default<T: GodotFfi>(
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
-pub unsafe trait GodotNullableFfi: Sized + GodotFfi {
+/// Types that can represent null-values.
+///
+/// Used to blanket implement various conversions over `Option<T>`.
+pub trait GodotNullableFfi: Sized + GodotFfi {
     fn flatten_option(opt: Option<Self>) -> Self;
     fn is_null(&self) -> bool;
 }

godot-macros/src/class/data_models/property.rs

@@ -173,7 +173,7 @@ pub fn make_property_impl(class_name: &Ident, fields: &Fields) -> TokenStream {
 
         export_tokens.push(quote! {
             use ::godot::sys::GodotFfi;
-            
+
             let (hint, hint_string) = #hint;
             let usage = #usage_flags;
 

godot-macros/src/lib.rs

@@ -423,13 +423,13 @@ pub fn derive_godot_compatible(input: TokenStream) -> TokenStream {
     translate(input, derive::derive_godot_compatible)
 }
 
-/// Derive macro for [ToVariant](../builtin/trait.ToVariant.html) on structs or enums.
+/// Derive macro for [ToGodot](../builtin/meta/trait.ToGodot.html) on structs or enums.
 ///
 /// # Example
 ///
 /// ```no_run
 /// # use godot::prelude::*;
-/// #[derive(FromVariant, ToVariant, PartialEq, Debug)]
+/// #[derive(FromGodot, ToGodot, GodotCompatible, PartialEq, Debug)]
 /// struct StructNamed {
 ///     field1: String,
 ///     field2: i32,
@@ -456,13 +456,13 @@ pub fn derive_to_godot(input: TokenStream) -> TokenStream {
     translate(input, derive::derive_to_godot)
 }
 
-/// Derive macro for [FromVariant](../builtin/trait.FromVariant.html) on structs or enums.
+/// Derive macro for [FromGodot](../builtin/meta/trait.FromVariant.html) on structs or enums.
 ///
 /// # Example
 ///
 /// ```no_run
 /// # use godot::prelude::*;
-/// #[derive(FromVariant, ToVariant, PartialEq, Debug)]
+/// #[derive(FromGodot, ToGodot, GodotCompatible, PartialEq, Debug)]
 /// struct StructNamed {
 ///     field1: String,
 ///     field2: i32,

itest/rust/build.rs

@@ -60,6 +60,7 @@ macro_rules! push_newtype {
             }
 
             impl godot::builtin::meta::ToGodot for $name {
+                #[allow(clippy::clone_on_copy)]
                 fn to_godot(&self) -> Self::Via {
                     self.0.clone()
                 }