diff --git a/.github/workflows/full-ci.yml b/.github/workflows/full-ci.yml index 119a6f008..34d427abf 100644 --- a/.github/workflows/full-ci.yml +++ b/.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 diff --git a/.github/workflows/minimal-ci.yml b/.github/workflows/minimal-ci.yml index 712781a19..5ab54c0ce 100644 --- a/.github/workflows/minimal-ci.yml +++ b/.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 diff --git a/godot-core/src/builtin/array.rs b/godot-core/src/builtin/array.rs index 08bb47b3b..619e3a1d5 100644 --- a/godot-core/src/builtin/array.rs +++ b/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 Array { /// 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 Array { /// 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 Array { /// /// 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) -> Self { self.subarray_impl(begin, end, step, false) @@ -289,7 +290,7 @@ impl Array { /// /// 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) -> Self { self.subarray_impl(begin, end, step, true) diff --git a/godot-core/src/builtin/callable.rs b/godot-core/src/builtin/callable.rs index b1874d6a9..79ad93a45 100644 --- a/godot-core/src/builtin/callable.rs +++ b/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`_ diff --git a/godot-core/src/builtin/color.rs b/godot-core/src/builtin/color.rs index 4b66a83a8..7c1827507 100644 --- a/godot-core/src/builtin/color.rs +++ b/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) diff --git a/godot-core/src/builtin/math/float.rs b/godot-core/src/builtin/math/float.rs index 01d77e658..0c52e718e 100644 --- a/godot-core/src/builtin/math/float.rs +++ b/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. /// diff --git a/godot-core/src/builtin/plane.rs b/godot-core/src/builtin/plane.rs index bcc77ee07..4931d6b87 100644 --- a/godot-core/src/builtin/plane.rs +++ b/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] diff --git a/godot-core/src/builtin/real.rs b/godot-core/src/builtin/real.rs index 416fc46e6..5c95eed0d 100644 --- a/godot-core/src/builtin/real.rs +++ b/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). diff --git a/godot-core/src/builtin/string/godot_string.rs b/godot-core/src/builtin/string/godot_string.rs index da0ce3b60..aa581039b 100644 --- a/godot-core/src/builtin/string/godot_string.rs +++ b/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 { diff --git a/godot-core/src/builtin/transform2d.rs b/godot-core/src/builtin/transform2d.rs index 4d0e5ed69..192f90d6f 100644 --- a/godot-core/src/builtin/transform2d.rs +++ b/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 } } diff --git a/godot-core/src/builtin/transform3d.rs b/godot-core/src/builtin/transform3d.rs index e8fb1946c..02613724e 100644 --- a/godot-core/src/builtin/transform3d.rs +++ b/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,8 +112,6 @@ 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()) @@ -121,8 +119,6 @@ impl Transform3D { /// 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 { diff --git a/godot-core/src/builtin/vectors/vector2i.rs b/godot-core/src/builtin/vectors/vector2i.rs index ab67dd98d..f53c913af 100644 --- a/godot-core/src/builtin/vectors/vector2i.rs +++ b/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)] diff --git a/godot-core/src/builtin/vectors/vector3i.rs b/godot-core/src/builtin/vectors/vector3i.rs index a8170398a..4dd37619b 100644 --- a/godot-core/src/builtin/vectors/vector3i.rs +++ b/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)] diff --git a/godot-core/src/builtin/vectors/vector4.rs b/godot-core/src/builtin/vectors/vector4.rs index 6a81fa7a6..814b7a7c1 100644 --- a/godot-core/src/builtin/vectors/vector4.rs +++ b/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, diff --git a/godot-core/src/builtin/vectors/vector4i.rs b/godot-core/src/builtin/vectors/vector4i.rs index 478dd5b38..daa864308 100644 --- a/godot-core/src/builtin/vectors/vector4i.rs +++ b/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)] diff --git a/godot-core/src/engine.rs b/godot-core/src/engine.rs index d70554c59..b4f8c355a 100644 --- a/godot-core/src/engine.rs +++ b/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: diff --git a/godot-core/src/obj/gd.rs b/godot-core/src/obj/gd.rs index 48cc6c04b..9714dedf5 100644 --- a/godot-core/src/obj/gd.rs +++ b/godot-core/src/obj/gd.rs @@ -267,7 +267,7 @@ impl Gd { /// ⚠️ 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 { self.cached_instance_id.get() } diff --git a/godot-ffi/src/compat/compat_4_1.rs b/godot-ffi/src/compat/compat_4_1.rs index 74bc185ba..e258e5870 100644 --- a/godot-ffi/src/compat/compat_4_1.rs +++ b/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: . use crate as sys; use crate::compat::BindingCompat; diff --git a/godot-ffi/src/godot_ffi.rs b/godot-ffi/src/godot_ffi.rs index 43b39368f..bb2d2edd0 100644 --- a/godot-ffi/src/godot_ffi.rs +++ b/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 . Virtual, } diff --git a/godot-macros/src/lib.rs b/godot-macros/src/lib.rs index d4b6740aa..313307923 100644 --- a/godot-macros/src/lib.rs +++ b/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)]