Several doc improvements

Author: Bromeon

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

@@ -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];
@@ -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

@@ -632,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};
 ///
@@ -644,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

@@ -202,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/[email protected]#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/[email protected]#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/[email protected]#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

@@ -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)]

godot/src/lib.rs

@@ -192,14 +192,15 @@ compile_error!("Must opt-in using `experimental-wasm` Cargo feature; keep in min
 #[cfg(all(feature = "double-precision", not(feature = "custom-godot")))]
 compile_error!("The feature `double-precision` currently requires `custom-godot` due to incompatibilities in the GDExtension API JSON.");
 
+/// Entry point and global init/shutdown of the library.
 pub mod init {
     pub use godot_core::init::*;
 
     // Re-exports
     pub use godot_macros::gdextension;
 }
 
-/// Register Rust symbols in Godot: classes, methods, enums...
+/// Register/export Rust symbols to Godot: classes, methods, enums...
 pub mod register {
     pub use godot_core::property;
     pub use godot_macros::{godot_api, Export, FromGodot, GodotClass, GodotConvert, ToGodot, Var};