Various doc improvements

Author: Bromeon

godot-core/src/meta/godot_convert/impls.rs

@@ -337,16 +337,6 @@ impl GodotType for u64 {
     impl_godot_scalar!(@shared_fns; i64, sys::GDEXTENSION_METHOD_ARGUMENT_METADATA_INT_IS_UINT64);
 }
 
-/// Test that `u64` does not implement `ToGodot/FromGodot`.
-///
-/// The impls are not provided since `u64` is not a natively supported type in GDScript (e.g. cannot be stored in a variant without altering the
-/// value). So `#[func]` does not support it. However, engine APIs may still need it, so there is codegen/macro support.
-///
-/// ```compile_fail
-/// # use godot::prelude::*;
-/// let value: u64 = 42;
-/// let variant = value.to_variant();  // Error: u64 does not implement ToGodot
-/// ```
 impl GodotConvert for u64 {
     type Via = u64;
 }
@@ -468,6 +458,14 @@ impl<T: ArrayElement> ToGodot for &[T] {
 //
 // Sanity check: comment-out ::godot::meta::ensure_func_bounds in func.rs, the 3 latter #[func] ones should fail.
 
+/// Test that `u64` cannot be converted to variant.
+///
+/// ```compile_fail
+/// # use godot::prelude::*;
+/// let variant = 100u64.to_variant();  // Error: u64 does not implement ToGodot
+/// ```
+fn __doctest_u64() {}
+
 /// Test that `*mut i32` cannot be converted to variant.
 ///
 /// ```compile_fail

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

@@ -21,6 +21,13 @@ use crate::meta::{ArgPassing, GodotType, ToArg};
 /// in Godot (without intermediate "via"). Every `GodotType` also implements `GodotConvert` with `Via = Self`.
 ///
 /// Please read the [`godot::meta` module docs][crate::meta] for further information about conversions.
+///
+/// # u64
+/// The type `u64` is **not** supported by `ToGodot` and `FromGodot` traits. You can thus not pass it in `#[func]` parameters/return types.
+///
+/// The reason is that Godot's `Variant` type, and therefore also GDScript, only support _signed_ 64-bit integers (`i64`).
+/// Implicitly wrapping `u64` to `i64` would be surprising behavior, as the value could suddenly change for large numbers.
+/// As such, godot-rust leaves this decision to users: it's possible to define a newtype around `u64` with custom `ToGodot`/`FromGodot` impls.
 #[doc(alias = "via", alias = "transparent")]
 #[diagnostic::on_unimplemented(
     message = "`GodotConvert` is needed for `#[func]` parameters/returns, as well as `#[var]` and `#[export]` properties",

godot-core/src/meta/traits.rs

@@ -179,7 +179,7 @@ pub trait GodotType: GodotConvert<Via = Self> + sealed::Sealed + Sized + 'static
 /// best-effort checks to detect such errors, however they are expensive and not bullet-proof. If you need very rigid type safety, stick to
 /// `i64` and `f64`. The other types however can be extremely convenient and work well, as long as you are aware of the limitations.
 ///
-/// `u64` is entirely unsupported since it cannot be safely stored inside a `Variant`.
+/// `u64` is [entirely unsupported](trait.GodotConvert.html#u64).
 ///
 /// Also, keep in mind that Godot uses `Variant` for each element. If performance matters and you have small element types such as `u8`,
 /// consider using packed arrays (e.g. `PackedByteArray`) instead.

godot-core/src/obj/script.rs

@@ -234,7 +234,7 @@ impl<T: ScriptInstance> Drop for ScriptInstanceData<T> {
     }
 }
 
-/// Creates a new  from a type that implements [`ScriptInstance`].
+/// Creates a raw pointer to a Godot script instance, from a Rust [`ScriptInstance`] object.
 ///
 /// See [`ScriptInstance`] for usage. Discarding the resulting value will result in a memory leak.
 ///
@@ -246,7 +246,7 @@ impl<T: ScriptInstance> Drop for ScriptInstanceData<T> {
 pub unsafe fn create_script_instance<T: ScriptInstance>(
     rust_instance: T,
     for_object: Gd<T::Base>,
-) -> crate::meta::RawPtr<*mut c_void> {
+) -> RawPtr<*mut c_void> {
     // Field grouping matches C header.
     let gd_instance = ScriptInstanceInfo {
         set_func: Some(script_instance_info::set_property_func::<T>),