Merge pull request #555 from godot-rust/qol/rename-register

Rename `bind` -> `register`; improve docs

godot-core/src/builtin/aabb.rs

@@ -385,7 +385,7 @@ impl Aabb {
 impl std::fmt::Display for Aabb {
     /// Formats `Aabb` to match godot's display style.
     ///
-    /// Example:
+    /// # Example
     /// ```
     /// use godot::prelude::*;
     /// let aabb = Aabb::new(Vector3::new(0.0, 0.0, 0.0), Vector3::new(1.0, 1.0, 1.0));

godot-core/src/builtin/array.rs

@@ -8,7 +8,7 @@
 use godot_ffi as sys;
 
 use crate::builtin::*;
-use crate::property::{Export, Property, PropertyHintInfo, TypeStringHint};
+use crate::property::{Export, PropertyHintInfo, TypeStringHint, Var};
 use std::fmt;
 use std::marker::PhantomData;
 use sys::{ffi_methods, interface_fn, GodotFfi};
@@ -677,7 +677,7 @@ impl<T: GodotType> fmt::Debug for Array<T> {
 impl<T: GodotType + fmt::Display> fmt::Display for Array<T> {
     /// Formats `Array` to match Godot's string representation.
     ///
-    /// Example:
+    /// # Example
     /// ```no_run
     /// # use godot::prelude::*;
     /// let a = array![1,2,3,4];
@@ -729,7 +729,7 @@ impl TypeStringHint for VariantArray {
     }
 }
 
-impl<T: GodotType> Property for Array<T> {
+impl<T: GodotType> Var for Array<T> {
     type Intermediate = Self;
 
     fn get_property(&self) -> Self::Intermediate {
@@ -985,13 +985,16 @@ impl<T: GodotType> PartialOrd for Array<T> {
 ///
 /// The type of the array is inferred from the arguments.
 ///
-/// Example:
+/// # Example
 /// ```no_run
 /// # use godot::prelude::*;
 /// let arr = array![3, 1, 4];  // Array<i32>
 /// ```
 ///
+/// # See also
 /// To create an `Array` of variants, see the [`varray!`] macro.
+///
+/// For dictionaries, a similar macro [`dict!`] exists.
 #[macro_export]
 macro_rules! array {
     ($($elements:expr),* $(,)?) => {
@@ -1007,15 +1010,18 @@ macro_rules! array {
 
 /// Constructs [`VariantArray`] literals, similar to Rust's standard `vec!` macro.
 ///
-/// The type of the array is always [`Variant`].
+/// The type of the array elements is always [`Variant`].
 ///
-/// Example:
+/// # Example
 /// ```no_run
 /// # use godot::prelude::*;
 /// let arr: VariantArray = varray![42_i64, "hello", true];
 /// ```
 ///
+/// # See also
 /// To create a typed `Array` with a single element type, see the [`array!`] macro.
+///
+/// For dictionaries, a similar macro [`dict!`] exists.
 #[macro_export]
 macro_rules! varray {
     // Note: use to_variant() and not Variant::from(), as that works with both references and values

godot-core/src/builtin/color.rs

@@ -520,7 +520,7 @@ fn to_be_words(mut u: u64) -> [u16; 4] {
 impl std::fmt::Display for Color {
     /// Formats `Color` to match Godot's string representation.
     ///
-    /// Example:
+    /// # Example
     /// ```
     /// use godot::prelude::*;
     /// let color = Color::from_rgba(1.0,1.0,1.0,1.0);

godot-core/src/builtin/dictionary.rs

@@ -8,16 +8,14 @@
 use godot_ffi as sys;
 
 use crate::builtin::meta::{FromGodot, ToGodot};
-use crate::builtin::{inner, Variant};
-use crate::property::{Export, Property, PropertyHintInfo, TypeStringHint};
-use std::fmt;
+use crate::builtin::{inner, Variant, VariantArray};
+use crate::property::{Export, PropertyHintInfo, TypeStringHint, Var};
 use std::marker::PhantomData;
-use std::ptr::addr_of_mut;
+use std::{fmt, ptr};
 use sys::types::OpaqueDictionary;
-use sys::{ffi_methods, interface_fn, AsUninit, GodotFfi, VariantType};
+use sys::{ffi_methods, interface_fn, AsUninit, GodotFfi};
 
 use super::meta::impl_godot_as_self;
-use super::VariantArray;
 
 /// Godot's `Dictionary` type.
 ///
@@ -339,7 +337,7 @@ impl Clone for Dictionary {
     }
 }
 
-impl Property for Dictionary {
+impl Var for Dictionary {
     type Intermediate = Self;
 
     fn get_property(&self) -> Self::Intermediate {
@@ -353,7 +351,7 @@ impl Property for Dictionary {
 
 impl TypeStringHint for Dictionary {
     fn type_string() -> String {
-        format!("{}:Dictionary", VariantType::Dictionary as i32)
+        format!("{}:Dictionary", sys::VariantType::Dictionary as i32)
     }
 }
 
@@ -484,7 +482,7 @@ impl<'a> DictionaryIter<'a> {
             iter_fn(
                 dictionary.var_sys(),
                 next_value.var_sys(),
-                addr_of_mut!(valid_u8),
+                ptr::addr_of_mut!(valid_u8),
             )
         };
         let valid = super::u8_to_bool(valid_u8);
@@ -634,7 +632,7 @@ impl<'a, K: FromGodot> Iterator for TypedKeys<'a, K> {
 /// Any value can be used as a key, but to use an expression you need to surround it
 /// in `()` or `{}`.
 ///
-/// Example:
+/// # Example
 /// ```no_run
 /// use godot::builtin::{dict, Variant};
 ///
@@ -646,6 +644,10 @@ impl<'a, K: FromGodot> Iterator for TypedKeys<'a, K> {
 ///     (1 + 2): "final",
 /// };
 /// ```
+///
+/// # See also
+///
+/// For arrays, similar macros [`array!`][macro@crate::builtin::array] and [`varray!`][macro@crate::builtin::varray] exist.
 #[macro_export]
 macro_rules! dict {
     ($($key:tt: $value:expr),* $(,)?) => {

godot-core/src/builtin/plane.rs

@@ -288,7 +288,7 @@ impl ApproxEq for Plane {
 impl std::fmt::Display for Plane {
     /// Formats `Plane` to match Godot's string representation.
     ///
-    /// Example:
+    /// # Example
     /// ```
     /// use godot::prelude::*;
     /// let plane = Plane::new(Vector3::new(1.0, 0.0, 0.0), 1.0);

godot-core/src/builtin/projection.rs

@@ -581,7 +581,7 @@ pub enum ProjectionEye {
 impl std::fmt::Display for Projection {
     /// Formats `Projection` to match Godot's string representation.
     ///
-    /// Example:
+    /// # Example
     /// ```
     /// use godot::prelude::*;
     /// let proj = Projection::new([

godot-core/src/builtin/real.rs

@@ -5,6 +5,8 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+/// Convenience conversion between `real` and `f32`/`f64`.
+///
 /// Clippy often complains if you do `f as f64` when `f` is already an `f64`. This trait exists to make it easy to
 /// convert between the different reals and floats without a lot of allowing clippy lints for your code.
 pub trait RealConv {
@@ -200,6 +202,8 @@ macro_rules! real {
 
 /// Array of reals.
 ///
+/// The expression has type `[real; N]` where `N` is the number of elements in the array.
+///
 /// # Example
 /// ```
 /// use godot_core::builtin::{real, reals};

godot-core/src/builtin/rect2.rs

@@ -278,7 +278,7 @@ impl ApproxEq for Rect2 {
 impl std::fmt::Display for Rect2 {
     /// Formats `Rect2` to match Godot's string representation.
     ///
-    /// Example:
+    /// # Example
     /// ```
     /// use godot::prelude::*;
     /// let rect = Rect2::new(Vector2::new(0.0, 0.0), Vector2::new(1.0, 1.0));

godot-core/src/builtin/rect2i.rs

@@ -279,7 +279,7 @@ impl_godot_as_self!(Rect2i);
 impl std::fmt::Display for Rect2i {
     /// Formats `Rect2i` to match Godot's string representation.
     ///
-    /// Example:
+    /// # Example
     /// ```
     /// use godot::prelude::*;
     /// let rect = Rect2i::new(Vector2i::new(0, 0), Vector2i::new(1, 1));

godot-core/src/builtin/rid.rs

@@ -101,7 +101,7 @@ impl Rid {
 impl std::fmt::Display for Rid {
     /// Formats `Rid` to match Godot's string representation.
     ///
-    /// Example:
+    /// # Example
     /// ```
     /// use godot::prelude::*;
     /// let id = Rid::new(1);

godot-core/src/log.rs

@@ -5,6 +5,8 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+//! Printing and logging functionality.
+
 #[macro_export]
 #[doc(hidden)]
 macro_rules! inner_godot_msg {
@@ -33,7 +35,7 @@ macro_rules! inner_godot_msg {
 
 /// Pushes a warning message to Godot's built-in debugger and to the OS terminal.
 ///
-/// _Godot equivalent: @GlobalScope.push_warning()_
+/// _Godot equivalent: [`@GlobalScope.push_warning()`](https://docs.godotengine.org/en/stable/classes/class_@globalscope.html#class-globalscope-method-push-warning)_.
 #[macro_export]
 macro_rules! godot_warn {
     ($fmt:literal $(, $args:expr)* $(,)?) => {
@@ -43,14 +45,15 @@ macro_rules! godot_warn {
 
 /// Pushes an error message to Godot's built-in debugger and to the OS terminal.
 ///
-/// _Godot equivalent: @GlobalScope.push_error()_
+/// _Godot equivalent: [`@GlobalScope.push_error()`](https://docs.godotengine.org/en/stable/classes/class_@globalscope.html#class-globalscope-method-push-error)_.
 #[macro_export]
 macro_rules! godot_error {
     ($fmt:literal $(, $args:expr)* $(,)?) => {
         $crate::inner_godot_msg!(print_error; $fmt $(, $args)*);
     };
 }
 
+/// Logs a script error to Godot's built-in debugger and to the OS terminal.
 #[macro_export]
 macro_rules! godot_script_error {
     ($fmt:literal $(, $args:expr)* $(,)?) => {
@@ -60,7 +63,7 @@ macro_rules! godot_script_error {
 
 /// Prints to the Godot console.
 ///
-/// _Godot equivalent: @GlobalScope.print()_
+/// _Godot equivalent: [`@GlobalScope.print()`](https://docs.godotengine.org/en/stable/classes/class_@globalscope.html#class-globalscope-method-print)_.
 #[macro_export]
 macro_rules! godot_print {
     ($fmt:literal $(, $args:expr)* $(,)?) => {
@@ -79,7 +82,7 @@ pub use crate::{godot_error, godot_print, godot_script_error, godot_warn};
 use crate::builtin::{StringName, Variant};
 use crate::sys::{self, GodotFfi};
 
-/// Prints to the Godot console, used by the godot_print! macro.
+/// Prints to the Godot console, used by the [`godot_print!`] macro.
 pub fn print(varargs: &[Variant]) {
     unsafe {
         let method_name = StringName::from("print");

godot-core/src/obj/gd.rs

@@ -19,7 +19,7 @@ use crate::builtin::{Callable, StringName};
 use crate::obj::Bounds;
 use crate::obj::{bounds, cap, EngineEnum, GdDerefTarget, GodotClass, Inherits};
 use crate::obj::{GdMut, GdRef, InstanceId};
-use crate::property::{Export, Property, PropertyHintInfo, TypeStringHint};
+use crate::property::{Export, PropertyHintInfo, TypeStringHint, Var};
 use crate::{callbacks, engine, out};
 
 use super::RawGd;
@@ -113,7 +113,7 @@ where
     /// The `init` function provides you with a `Base<T::Base>` object that you can use inside your `T`, which
     /// is then wrapped in a `Gd<T>`.
     ///
-    /// Example:
+    /// # Example
     /// ```no_run
     /// # use godot::prelude::*;
     /// #[derive(GodotClass)]
@@ -615,7 +615,7 @@ impl<T: GodotClass> TypeStringHint for Gd<T> {
     }
 }
 
-impl<T: GodotClass> Property for Gd<T> {
+impl<T: GodotClass> Var for Gd<T> {
     type Intermediate = Self;
 
     fn get_property(&self) -> Self {

godot-core/src/obj/onready.rs

@@ -5,7 +5,7 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-use crate::property::{Export, Property, PropertyHintInfo};
+use crate::property::{Export, PropertyHintInfo, Var};
 use std::mem;
 
 /// Ergonomic late-initialization container with `ready()` support.
@@ -187,7 +187,7 @@ impl<T> std::ops::DerefMut for OnReady<T> {
     }
 }
 
-impl<T: Property> Property for OnReady<T> {
+impl<T: Var> Var for OnReady<T> {
     type Intermediate = T::Intermediate;
 
     fn get_property(&self) -> Self::Intermediate {