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

Enforce rustdoc checks in CI

Author: Bromeon

.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 }
     }