Note about element type safety of Array<T>

Author: Bromeon

godot-core/src/builtin/collections/array.rs

@@ -109,6 +109,22 @@ use sys::{ffi_methods, interface_fn, GodotFfi};
 /// compiler will enforce this as long as you use only Rust threads, but it cannot protect against
 /// concurrent modification on other threads (e.g. created through GDScript).
 ///
+/// # Element type safety
+///
+/// We provide a richer set of element types than Godot, for convenience and stronger invariants in your _Rust_ code.
+/// This, however, means that the Godot representation of such arrays is not capable of incorporating the additional "Rust-side" information.
+/// This can lead to situations where GDScript code or the editor UI can insert values that do not fulfill the Rust-side invariants.
+/// The library offers some best-effort protection in Debug mode, but certain errors may only occur on element access, in the form of panics.
+///
+/// Concretely, the following types lose type information when passed to Godot. If you want 100% bullet-proof arrays, avoid those.
+/// - Non-`i64` integers: `i8`, `i16`, `i32`, `u8`, `u16`, `u32`. (`u64` is unsupported).
+/// - Non-`f64` floats: `f32`.
+/// - Non-null objects: [`Gd<T>`][crate::obj::Gd].
+///   Godot generally allows `null` in arrays due to default-constructability, e.g. when using `resize()`.
+///   The Godot-faithful (but less convenient) alternative is to use `Option<Gd<T>>` element types.
+/// - Objects with dyn-trait association: [`DynGd<T, D>`][crate::obj::DynGd].
+///   Godot doesn't know Rust traits and will only see the `T` part.
+///
 /// # Godot docs
 ///
 /// [`Array[T]` (stable)](https://docs.godotengine.org/en/stable/classes/class_array.html)