Merge pull request #375 from godot-rust/qol/rustdoc-lints

Enforce rustdoc checks in CI

.github/workflows/full-ci.yml

@@ -47,6 +47,25 @@ jobs:
         run: cargo fmt --all -- --check
 
 
+  # Needs to be its own job (apart from sync-doc), because lints don't work with --no-deps, and because it contributes to ci-status.
+  doc-lints:
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: "Install Rust"
+      uses: ./.github/composite/rust
+      with:
+        components: rustdoc
+
+    - name: "Check rustdoc"
+      env:
+        RUSTDOCFLAGS: >
+          -D rustdoc::broken-intra-doc-links -D rustdoc::private-intra-doc-links -D rustdoc::invalid-codeblock-attributes 
+          -D rustdoc::invalid-rust-codeblocks -D rustdoc::invalid-html-tags -D rustdoc::bare-urls -D rustdoc::unescaped-backticks
+      run: cargo doc -p godot
+
+
   clippy:
     runs-on: ubuntu-20.04
     steps:
@@ -299,6 +318,7 @@ jobs:
     if: always() && (github.event_name == 'merge_group' || github.event_name == 'push')
     needs:
       - rustfmt
+      - doc-lints
       - clippy
       - unit-test
       - godot-itest

.github/workflows/minimal-ci.yml

@@ -52,6 +52,25 @@ jobs:
         run: cargo fmt --all -- --check
 
 
+  # Needs to be its own job (apart from sync-doc), because lints don't work with --no-deps, and because it contributes to ci-status.
+  doc-lints:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: "Install Rust"
+        uses: ./.github/composite/rust
+        with:
+          components: rustdoc
+
+      - name: "Check rustdoc"
+        env:
+          RUSTDOCFLAGS: >
+            -D rustdoc::broken-intra-doc-links -D rustdoc::private-intra-doc-links -D rustdoc::invalid-codeblock-attributes 
+            -D rustdoc::invalid-rust-codeblocks -D rustdoc::invalid-html-tags -D rustdoc::bare-urls -D rustdoc::unescaped-backticks
+        run: cargo doc -p godot
+
+
   clippy:
     runs-on: ubuntu-20.04
     steps:
@@ -201,6 +220,7 @@ jobs:
     if: always()
     needs:
       - rustfmt
+      - doc-lints
       - clippy
       - unit-test
       - godot-itest

godot-core/src/builtin/array.rs

@@ -35,7 +35,8 @@ use sys::{ffi_methods, interface_fn, GodotFfi};
 /// refer to the same underlying array, and changes to one are visible in the other.
 ///
 /// To create a copy that shares data with the original array, use [`Share::share()`]. If you want
-/// to create a copy of the data, use [`duplicate_shallow()`] or [`duplicate_deep()`].
+/// to create a copy of the data, use [`duplicate_shallow()`][Self::duplicate_shallow] or
+/// [`duplicate_deep()`][Self::duplicate_deep].
 ///
 /// # Thread safety
 ///
@@ -243,8 +244,8 @@ impl<T: VariantMetadata> Array<T> {
     /// Returns a shallow copy of the array. All array elements are copied, but any reference types
     /// (such as `Array`, `Dictionary` and `Object`) will still refer to the same value.
     ///
-    /// To create a deep copy, use [`duplicate_deep()`] instead. To create a new reference to the
-    /// same array data, use [`share()`].
+    /// To create a deep copy, use [`duplicate_deep()`][Self::duplicate_deep] instead.
+    /// To create a new reference to the same array data, use [`share()`][Share::share].
     pub fn duplicate_shallow(&self) -> Self {
         let duplicate: VariantArray = self.as_inner().duplicate(false);
         // SAFETY: duplicate() returns a typed array with the same type as Self
@@ -255,8 +256,8 @@ impl<T: VariantMetadata> Array<T> {
     /// will not be shared with the original array. Note that any `Object`-derived elements will
     /// still be shallow copied.
     ///
-    /// To create a shallow copy, use [`duplicate_shallow()`] instead. To create a new reference to
-    /// the same array data, use [`share()`].
+    /// To create a shallow copy, use [`duplicate_shallow()`][Self::duplicate_shallow] instead.
+    /// To create a new reference to the same array data, use [`share()`][Share::share].
     pub fn duplicate_deep(&self) -> Self {
         let duplicate: VariantArray = self.as_inner().duplicate(true);
         // SAFETY: duplicate() returns a typed array with the same type as Self
@@ -273,7 +274,7 @@ impl<T: VariantMetadata> Array<T> {
     ///
     /// Array elements are copied to the slice, but any reference types (such as `Array`,
     /// `Dictionary` and `Object`) will still refer to the same value. To create a deep copy, use
-    /// [`subarray_deep()`] instead.
+    /// [`subarray_deep()`][Self::subarray_deep] instead.
     #[doc(alias = "slice")]
     pub fn subarray_shallow(&self, begin: usize, end: usize, step: Option<isize>) -> Self {
         self.subarray_impl(begin, end, step, false)
@@ -289,7 +290,7 @@ impl<T: VariantMetadata> Array<T> {
     ///
     /// All nested arrays and dictionaries are duplicated and will not be shared with the original
     /// array. Note that any `Object`-derived elements will still be shallow copied. To create a
-    /// shallow copy, use [`subarray_shallow()`] instead.
+    /// shallow copy, use [`subarray_shallow()`][Self::subarray_shallow] instead.
     #[doc(alias = "slice")]
     pub fn subarray_deep(&self, begin: usize, end: usize, step: Option<isize>) -> Self {
         self.subarray_impl(begin, end, step, true)

godot-core/src/builtin/callable.rs

@@ -150,7 +150,7 @@ impl Callable {
 
     /// Returns true if this callable has no target to call the method on.
     ///
-    /// This is not the negated form of [`is_valid`], as `is_valid` will return `false` if the callable has a
+    /// This is not the negated form of [`is_valid`][Self::is_valid], as `is_valid` will return `false` if the callable has a
     /// target but the method does not exist.
     ///
     /// _Godot equivalent: `is_null`_

godot-core/src/builtin/color.rs

@@ -242,14 +242,14 @@ impl Color {
     }
 
     /// Creates a new color resulting by making this color darker by the specified amount (ratio
-    /// from 0.0 to 1.0). See also [`lightened`].
+    /// from 0.0 to 1.0). See also [`lightened`][Self::lightened].
     #[must_use]
     pub fn darkened(self, amount: f64) -> Self {
         self.as_inner().darkened(amount)
     }
 
     /// Creates a new color resulting by making this color lighter by the specified amount, which
-    /// should be a ratio from 0.0 to 1.0. See also [`darken`].
+    /// should be a ratio from 0.0 to 1.0. See also [`darkened`][Self::darkened].
     #[must_use]
     pub fn lightened(self, amount: f64) -> Self {
         self.as_inner().lightened(amount)

godot-core/src/builtin/math/float.rs

@@ -25,7 +25,7 @@ pub trait FloatExt: private::Sealed + Copy {
     fn lerp(self, to: Self, weight: Self) -> Self;
 
     /// Check if two angles are approximately equal, by comparing the distance
-    /// between the points on the unit circle with 0 using [`is_equal_approx`].
+    /// between the points on the unit circle with 0 using [`real::approx_eq`].
     fn is_angle_equal_approx(self, other: Self) -> bool;
 
     /// Check if `self` is within [`Self::CMP_EPSILON`] of `0.0`.
@@ -38,7 +38,7 @@ pub trait FloatExt: private::Sealed + Copy {
 
     /// Godot's `sign` function, returns `0.0` when self is `0.0`.
     ///
-    /// See also [`signum`](Self::signum), which always returns `-1.0` or `1.0` (or `NaN`).
+    /// See also [`f32::signum`] and [`f64::signum`], which always return `-1.0` or `1.0` (or `NaN`).
     fn sign(self) -> Self;
 
     /// Returns the derivative at the given `t` on a one-dimensional Bézier curve defined by the given
@@ -69,8 +69,8 @@ pub trait FloatExt: private::Sealed + Copy {
     /// Linearly interpolates between two angles (in radians) by a `weight` value
     /// between 0.0 and 1.0.
     ///
-    /// Similar to [`lerp`], but interpolates correctly when the angles wrap around
-    /// [`TAU`].
+    /// Similar to [`lerp`][Self::lerp], but interpolates correctly when the angles wrap around
+    /// [`TAU`][crate::builtin::real_consts::TAU].
     ///
     /// The resulting angle is not normalized.
     ///

godot-core/src/builtin/plane.rs

@@ -127,7 +127,7 @@ impl Plane {
     /// Finds whether a point is inside the plane or not.
     ///
     /// A point is considered part of the plane if its distance to it is less or equal than
-    /// [`CMP_EPSILON`][crate::builtin::CMP_EPSILON].
+    /// [`CMP_EPSILON`][FloatExt::CMP_EPSILON].
     ///
     /// _Godot equivalent: `Plane.has_point(Vector3 point, float tolerance=1e-05)`_
     #[inline]

godot-core/src/builtin/real.rs

@@ -35,7 +35,7 @@ mod real_mod {
     /// This type is `f32` by default, and `f64` when the Cargo feature `double-precision` is enabled.
     ///
     /// This is not the `float` type in GDScript; that type is always 64-bits. Rather, many structs in Godot may use
-    /// either 32-bit or 64-bit floats, for example [`Vector2`](super::Vector2). To convert between [`real`] and [`f32`] or
+    /// either 32-bit or 64-bit floats, for example [`Vector2`][crate::builtin::Vector2]. To convert between [`real`] and [`f32`] or
     /// [`f64`], see [`RealConv`](super::RealConv).
     ///
     /// See also the [Godot docs on float](https://docs.godotengine.org/en/stable/classes/class_float.html).

godot-core/src/builtin/string/godot_string.rs

@@ -49,7 +49,7 @@ impl GodotString {
 
     /// Gets the internal chars slice from a [`GodotString`].
     ///
-    /// Note: This operation is *O*(*n*). Consider using [`chars_unchecked`]
+    /// Note: This operation is *O*(*n*). Consider using [`chars_unchecked`][Self::chars_unchecked]
     /// if you can make sure the string is a valid UTF-32.
     pub fn chars_checked(&self) -> &[char] {
         unsafe {

godot-core/src/builtin/transform2d.rs

@@ -24,8 +24,6 @@ use std::ops::{Mul, MulAssign};
 /// [ a.x  b.x  origin.x ]
 /// [ a.y  b.y  origin.y ]
 /// ```
-///
-/// For methods that don't take translation into account, see [`Basis2D`].
 #[derive(Default, Copy, Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[repr(C)]
@@ -72,7 +70,7 @@ impl Transform2D {
 
     /// Create a new `Transform2D` with the given column vectors.
     ///
-    /// _Godot equivalent: `Transform2D(Vector2 x_axis, Vector2 y_axis, Vector2 origin)_
+    /// _Godot equivalent: `Transform2D(Vector2 x_axis, Vector2 y_axis, Vector2 origin)`_
     pub const fn from_cols(a: Vector2, b: Vector2, origin: Vector2) -> Self {
         Self { a, b, origin }
     }

godot-core/src/builtin/transform3d.rs

@@ -61,14 +61,14 @@ impl Transform3D {
 
     /// Create a new transform from a [`Basis`] and a [`Vector3`].
     ///
-    /// _Godot equivalent: Transform3D(Basis basis, Vector3 origin)_
+    /// _Godot equivalent: `Transform3D(Basis basis, Vector3 origin)`_
     pub const fn new(basis: Basis, origin: Vector3) -> Self {
         Self { basis, origin }
     }
 
     /// Create a new transform from 4 matrix-columns.
     ///
-    /// _Godot equivalent: Transform3D(Vector3 x_axis, Vector3 y_axis, Vector3 z_axis, Vector3 origin)_
+    /// _Godot equivalent: `Transform3D(Vector3 x_axis, Vector3 y_axis, Vector3 z_axis, Vector3 origin)`_
     pub const fn from_cols(a: Vector3, b: Vector3, c: Vector3, origin: Vector3) -> Self {
         Self {
             basis: Basis::from_cols(a, b, c),
@@ -79,7 +79,7 @@ impl Transform3D {
     /// Constructs a Transform3d from a Projection by trimming the last row of
     /// the projection matrix.
     ///
-    /// _Godot equivalent: Transform3D(Projection from)_
+    /// _Godot equivalent: `Transform3D(Projection from)`_
     pub fn from_projection(proj: Projection) -> Self {
         let a = Vector3::new(proj.cols[0].x, proj.cols[0].y, proj.cols[0].z);
         let b = Vector3::new(proj.cols[1].x, proj.cols[1].y, proj.cols[1].z);
@@ -112,17 +112,13 @@ impl Transform3D {
 
     /// Returns the inverse of the transform, under the assumption that the
     /// transformation is composed of rotation, scaling and translation.
-    ///
-    /// _Godot equivalent: Transform3D.affine_inverse()_
     #[must_use]
     pub fn affine_inverse(self) -> Self {
         self.glam(|aff| aff.inverse())
     }
 
     /// Returns a transform interpolated between this transform and another by
     /// a given weight (on the range of 0.0 to 1.0).
-    ///
-    /// _Godot equivalent: Transform3D.interpolate_with()_
     #[must_use]
     pub fn interpolate_with(self, other: Self, weight: real) -> Self {
         let src_scale = self.basis.scale();
@@ -142,10 +138,8 @@ impl Transform3D {
         }
     }
 
-    /// Returns `true if this transform is finite by calling `is_finite` on the
+    /// Returns true if this transform is finite by calling `is_finite` on the
     /// basis and origin.
-    ///
-    /// _Godot equivalent: Transform3D.is_finite()_
     pub fn is_finite(&self) -> bool {
         self.basis.is_finite() && self.origin.is_finite()
     }
@@ -154,8 +148,6 @@ impl Transform3D {
     /// points towards the `target` position.
     ///
     /// See [`Basis::new_looking_at()`] for more information.
-    ///
-    /// _Godot equivalent: Transform3D.looking_at()_
     #[cfg(before_api = "4.1")]
     #[must_use]
     pub fn looking_at(self, target: Vector3, up: Vector3) -> Self {

godot-core/src/builtin/vectors/vector2i.rs

@@ -20,8 +20,8 @@ use std::fmt;
 ///
 /// It uses integer coordinates and is therefore preferable to [`Vector2`] when exact precision is
 /// required. Note that the values are limited to 32 bits, and unlike [`Vector2`] this cannot be
-/// configured with an engine build option. Use `i64` or [`PackedInt64Array`] if 64-bit values are
-/// needed.
+/// configured with an engine build option. Use `i64` or [`PackedInt64Array`][crate::builtin::PackedInt64Array]
+/// if 64-bit values are needed.
 #[derive(Default, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[repr(C)]

godot-core/src/builtin/vectors/vector3i.rs

@@ -20,8 +20,8 @@ use crate::builtin::{real, RVec3, Vector3, Vector3Axis};
 ///
 /// It uses integer coordinates and is therefore preferable to [`Vector3`] when exact precision is
 /// required. Note that the values are limited to 32 bits, and unlike [`Vector3`] this cannot be
-/// configured with an engine build option. Use `i64` or [`PackedInt64Array`] if 64-bit values are
-/// needed.
+/// configured with an engine build option. Use `i64` or [`PackedInt64Array`][crate::builtin::PackedInt64Array]
+/// if 64-bit values are needed.
 #[derive(Default, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[repr(C)]

godot-core/src/builtin/vectors/vector4.rs

@@ -55,7 +55,7 @@ impl Vector4 {
         Self::new(v, v, v, v)
     }
 
-    /// Constructs a new `Vector3` from a [`Vector3i`].
+    /// Constructs a new `Vector3` from a [`Vector3i`][crate::builtin::Vector3i].
     pub const fn from_vector4i(v: Vector4i) -> Self {
         Self {
             x: v.x as real,

godot-core/src/builtin/vectors/vector4i.rs

@@ -18,8 +18,8 @@ use std::fmt;
 ///
 /// It uses integer coordinates and is therefore preferable to [`Vector4`] when exact precision is
 /// required. Note that the values are limited to 32 bits, and unlike [`Vector4`] this cannot be
-/// configured with an engine build option. Use `i64` or [`PackedInt64Array`] if 64-bit values are
-/// needed.
+/// configured with an engine build option. Use `i64` or [`PackedInt64Array`][crate::builtin::PackedInt64Array]
+/// if 64-bit values are needed.
 #[derive(Default, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[repr(C)]

godot-core/src/engine.rs

@@ -151,7 +151,7 @@ where
 ///
 /// If the resource cannot be loaded, or is not of type `T` or inherited, this method returns `None`.
 ///
-/// This method is a simplified version of [`ResourceLoader::load()`][crate::api::ResourceLoader::load],
+/// This method is a simplified version of [`ResourceLoader::load()`][crate::engine::ResourceLoader::load],
 /// which can be used for more advanced scenarios.
 ///
 /// # Note:

godot-core/src/obj/gd.rs

@@ -267,7 +267,7 @@ impl<T: GodotClass> Gd<T> {
     /// ⚠️ Returns the instance ID of this object, or `None` if no instance ID is cached.
     ///
     /// This function does not check that the returned instance ID points to a valid instance!
-    /// Unless performance is a problem, use [`instance_id_or_none`].
+    /// Unless performance is a problem, use [`instance_id_or_none`][Self::instance_id_or_none] instead.
     pub fn instance_id_or_none_unchecked(&self) -> Option<InstanceId> {
         self.cached_instance_id.get()
     }

godot-ffi/src/compat/compat_4_1.rs

@@ -9,7 +9,7 @@
 //! The extension entry point is passed `get_proc_address` function pointer, which can be used to load all other
 //! GDExtension FFI functions dynamically. This is a departure from the previous struct-based approach.
 //!
-//! Relevant upstream PR: https://github.com/godotengine/godot/pull/76406
+//! Relevant upstream PR: <https://github.com/godotengine/godot/pull/76406>.
 
 use crate as sys;
 use crate::compat::BindingCompat;

godot-ffi/src/godot_ffi.rs

@@ -241,7 +241,7 @@ pub enum PtrcallType {
     /// To get a `GDExtensionObjectPtr` from a `GDExtensionRefPtr`, you must use `ref_get_object`, and to
     /// set a `GDExtensionRefPtr` to some object, you must use `ref_set_object`.
     ///
-    /// See also https://github.com/godotengine/godot-cpp/issues/954.
+    /// See also <https://github.com/godotengine/godot-cpp/issues/954>.
     Virtual,
 }
 

godot-macros/src/lib.rs

@@ -402,7 +402,7 @@ pub fn derive_native_class(input: TokenStream) -> TokenStream {
     translate(input, derive_godot_class::transform)
 }
 
-/// Derive macro for [ToVariant](godot::builtin::ToVariant) on structs or enums.
+/// Derive macro for [ToVariant](../builtin/trait.ToVariant.html) on structs or enums.
 ///
 /// # Example
 ///
@@ -435,7 +435,7 @@ pub fn derive_to_variant(input: TokenStream) -> TokenStream {
     translate(input, derive_to_variant::transform)
 }
 
-/// Derive macro for [FromVariant](godot::builtin::FromVariant) on structs or enums.
+/// Derive macro for [FromVariant](../builtin/trait.FromVariant.html) on structs or enums.
 ///
 /// # Example
 ///
@@ -469,7 +469,7 @@ pub fn derive_from_variant(input: TokenStream) -> TokenStream {
     translate(input, derive_from_variant::transform)
 }
 
-/// Derive macro for [Property](godot::bind::property::Property) on enums.
+/// Derive macro for [Property](../bind/property/trait.Property.html) on enums.
 ///
 /// Currently has some tight requirements which are expected to be softened as implementation expands:
 /// - Only works for enums, structs aren't supported by this derive macro at the moment.
@@ -512,7 +512,7 @@ pub fn derive_property(input: TokenStream) -> TokenStream {
     translate(input, derive_property::transform)
 }
 
-/// Derive macro for [Export](godot::bind::property::Property) on enums.
+/// Derive macro for [Export](../bind/property/trait.Export.html) on enums.
 ///
 /// Currently has some tight requirements which are expected to be softened as implementation expands, see requirements for [Property]
 #[proc_macro_derive(Export)]