Usage docs for Array + Dictionary

Author: Bromeon

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

@@ -45,6 +45,60 @@ use sys::{ffi_methods, interface_fn, GodotFfi};
 /// If you want to create a copy of the data, use [`duplicate_shallow()`][Self::duplicate_shallow]
 /// or [`duplicate_deep()`][Self::duplicate_deep].
 ///
+/// # Typed array example
+///
+/// ```no_run
+/// # use godot::prelude::*;
+/// // Create typed Array<i64> and add values.
+/// let mut array = Array::new();
+/// array.push(10);
+/// array.push(20);
+/// array.push(30);
+///
+/// // Or create the same array in a single expression.
+/// let array = array![10, 20, 30];
+///
+/// // Access elements.
+/// let value: i64 = array.at(0); // 10
+/// let maybe: Option<i64> = array.get(3); // None
+///
+/// // Iterate over i64 elements.
+/// for value in array.iter_shared() {
+///    println!("{value}");
+/// }
+///
+/// // Clone array (shares the reference), and overwrite elements through clone.
+/// let mut cloned = array.clone();
+/// cloned.set(0, 50); // [50, 20, 30]
+/// cloned.remove(1);  // [50, 30]
+/// cloned.pop();      // [50]
+///
+/// // Changes will be reflected in the original array.
+/// assert_eq!(array.len(), 1);
+/// assert_eq!(array.front(), Some(50));
+/// ```
+///
+/// # Untyped array example
+///
+/// ```no_run
+/// # use godot::prelude::*;
+/// // VariantArray allows dynamic element types.
+/// let mut array = VariantArray::new();
+/// array.push(10.to_variant());
+/// array.push("Hello".to_variant());
+///
+/// // Or equivalent, use the `varray!` macro which converts each element.
+/// let array = varray![10, "Hello"];
+///
+/// // Access elements.
+/// let value: Variant = array.at(0);
+/// let value: i64 = array.at(0).to(); // Variant::to() extracts i64.
+/// let maybe: Result<i64, _> = array.at(1).try_to(); // "Hello" is not i64 -> Err.
+/// let maybe: Option<Variant> = array.get(3);
+///
+/// // ...and so on.
+/// ```
+///
 /// # Thread safety
 ///
 /// Usage is safe if the `Array` is used on a single thread only. Concurrent reads on

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

@@ -23,6 +23,53 @@ use std::{fmt, ptr};
 /// The keys and values of the dictionary are all `Variant`s, so they can be of different types.
 /// Variants are designed to be generally cheap to clone.
 ///
+/// # Dictionary example
+///
+/// ```no_run
+/// # use godot::prelude::*;
+/// // Create empty dictionary and add key-values pairs.
+/// let mut dict = Dictionary::new();
+/// dict.set("str", "Hello");
+/// dict.set("num", 23);
+///
+/// // Keys don't need to be strings.
+/// let coord = Vector2i::new(0, 1);
+/// dict.set(coord, "Tile77");
+///
+/// // Or create the same dictionary in a single expression.
+/// let dict = dict! {
+///    "str": "Hello",
+///    "num": 23,
+///    coord: "Tile77",
+/// };
+///
+/// // Access elements.
+/// let value: Variant = dict.at("str");
+/// let value: GString = dict.at("str").to(); // Variant::to() extracts GString.
+/// let maybe: Option<Variant> = dict.get("absent_key");
+///
+/// // Iterate over key-value pairs as (Variant, Variant).
+/// for (key, value) in dict.iter_shared() {
+///     println!("{key} => {value}");
+/// }
+///
+/// // Use typed::<K, V>() to get typed iterators.
+/// for (key, value) in dict.iter_shared().typed::<GString, Variant>() {
+///     println!("{key} => {value}");
+/// }
+///
+/// // Clone dictionary (shares the reference), and overwrite elements through clone.
+/// let mut cloned = dict.clone();
+/// cloned.remove("num");
+///
+/// // Overwrite with set(); use insert() to get the previous value.
+/// let prev = cloned.insert("str", "Goodbye"); // prev == Some("Hello")
+///
+/// // Changes will be reflected in the original dictionary.
+/// assert_eq!(dict.at("str"), "Goodbye".to_variant());
+/// assert_eq!(dict.get("num"), None);
+/// ```
+///
 /// # Thread safety
 ///
 /// The same principles apply as for [`VariantArray`]. Consult its documentation for details.
@@ -246,7 +293,7 @@ impl Dictionary {
     /// Note that it's possible to modify the `Dictionary` through another reference while iterating over it. This will not result in
     /// unsoundness or crashes, but will cause the iterator to behave in an unspecified way.
     ///
-    /// Use `iter_shared().typed::<K, V>()` to iterate over `(K, V)` pairs instead.
+    /// Use `dict.iter_shared().typed::<K, V>()` to iterate over `(K, V)` pairs instead.
     pub fn iter_shared(&self) -> Iter<'_> {
         Iter::new(self)
     }
@@ -259,7 +306,7 @@ impl Dictionary {
     /// Note that it's possible to modify the `Dictionary` through another reference while iterating over it. This will not result in
     /// unsoundness or crashes, but will cause the iterator to behave in an unspecified way.
     ///
-    /// Use `.keys_shared.typed::<K>()` to iterate over `K` keys instead.
+    /// Use `dict.keys_shared().typed::<K>()` to iterate over `K` keys instead.
     pub fn keys_shared(&self) -> Keys<'_> {
         Keys::new(self)
     }

godot-core/src/builtin/quaternion.rs

@@ -12,6 +12,9 @@ use crate::builtin::math::{ApproxEq, FloatExt, GlamConv, GlamType};
 use crate::builtin::{inner, real, Basis, EulerOrder, RQuat, RealConv, Vector3};
 use std::ops::{Add, AddAssign, Div, DivAssign, Mul, MulAssign, Neg, Sub, SubAssign};
 
+/// Unit quaternion to represent 3D rotations.
+///
+/// See also [`Quaternion`](https://docs.godotengine.org/en/stable/classes/class_quaternion.html) in the Godot documentation.
 #[derive(Copy, Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[repr(C)]