From c9d26053852910e60e7374bf6d8ec204061d31ff Mon Sep 17 00:00:00 2001 From: ApsisRS contributors Date: Sat, 26 Sep 2026 23:37:48 +0800 Subject: [PATCH] docs: fix the broken intra doc links and check them in CI Running rustdoc with -D warnings found nine broken links: a misspelt WGS84, links to methods and constants that are private or in a crate that is not a dependency, and three redundant explicit targets. Fix each and add a documentation step to CI so a doc comment cannot drift away from the code it describes without the build noticing. --- .github/workflows/ci.yml | 6 ++++++ crates/foundation/apsis-units/src/lib.rs | 2 +- crates/network/apsis-routing/src/lib.rs | 2 +- crates/orbit/apsis-ephemeris/src/lib.rs | 2 +- crates/orbit/apsis-ephemeris/src/sampler.rs | 2 +- crates/orbit/apsis-kepler/src/anomaly.rs | 2 +- crates/physics/apsis-frames/src/iau2000/precession.rs | 4 ++-- crates/physics/apsis-geodesy/src/lib.rs | 2 +- crates/rf/apsis-antenna/src/lib.rs | 2 +- crates/sim/apsis-sim-engine/src/lib.rs | 2 +- 10 files changed, 16 insertions(+), 10 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4ecdb0b..e7c0beb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -37,6 +37,12 @@ jobs: # meaningful on a quiet machine, but it must still compile so that it # does not rot. run: cargo build -p apsis-rs --features full --example bench + - name: Documentation + # Catches a doc link that no longer resolves, which is how a doc + # comment drifts away from the code it describes. + env: + RUSTDOCFLAGS: -D warnings + run: cargo doc --workspace --all-features --no-deps - name: Check the layer rule # README.md states that a crate may only depend on layers to its # left. Nothing else in the build enforces that, so a reverse diff --git a/crates/foundation/apsis-units/src/lib.rs b/crates/foundation/apsis-units/src/lib.rs index 59f88bd..45b46f0 100644 --- a/crates/foundation/apsis-units/src/lib.rs +++ b/crates/foundation/apsis-units/src/lib.rs @@ -3,7 +3,7 @@ //! Each quantity is a newtype over `f64` that carries its unit in the type //! system, so a length cannot be passed where a duration is expected. Units //! of the same dimension convert through -//! [`Quantity::to_unit`](apsis_core::Quantity::to_unit), and each unit also +//! [`Quantity::to_unit`], and each unit also //! offers direct conversions for the common cases. //! //! A newtype implements both [`Unit`] and [`Quantity`], with its own type as diff --git a/crates/network/apsis-routing/src/lib.rs b/crates/network/apsis-routing/src/lib.rs index 84659f2..4600502 100644 --- a/crates/network/apsis-routing/src/lib.rs +++ b/crates/network/apsis-routing/src/lib.rs @@ -2,7 +2,7 @@ //! //! The topology of a satellite network changes as the satellites move, so a //! route is only valid over an interval. This crate computes least cost -//! routes through a [`Topology`](apsis_topology::Topology) and reports the +//! routes through a [`Topology`] and reports the //! route together with the time it remains valid. //! //! Two forms of routing are provided: diff --git a/crates/orbit/apsis-ephemeris/src/lib.rs b/crates/orbit/apsis-ephemeris/src/lib.rs index da944a0..e2df21a 100644 --- a/crates/orbit/apsis-ephemeris/src/lib.rs +++ b/crates/orbit/apsis-ephemeris/src/lib.rs @@ -13,7 +13,7 @@ //! two-body theory, or read from a file all work the same way. //! - [`Sampler`] fills a table by calling a function that produces a state //! from a time. In this workspace that function is normally -//! [`apsis_sgp4::Satellite::propagate_at`], but the sampler only requires +//! `apsis_sgp4::Satellite::propagate_at`, but the sampler only requires //! a closure, so a test can use an analytic function. //! //! Interpolation is Hermite cubic, which uses both the position and the diff --git a/crates/orbit/apsis-ephemeris/src/sampler.rs b/crates/orbit/apsis-ephemeris/src/sampler.rs index b3f1c0a..b419532 100644 --- a/crates/orbit/apsis-ephemeris/src/sampler.rs +++ b/crates/orbit/apsis-ephemeris/src/sampler.rs @@ -94,7 +94,7 @@ impl Sampler { /// /// The function maps a time in seconds to a position and velocity. In /// this workspace it is normally a closure over - /// [`apsis_sgp4::Satellite::propagate_at`], but any function works, so + /// `apsis_sgp4::Satellite::propagate_at`, but any function works, so /// the sampler can be tested against an analytic orbit. /// /// Returns an error when the sampler is not usable or when the function diff --git a/crates/orbit/apsis-kepler/src/anomaly.rs b/crates/orbit/apsis-kepler/src/anomaly.rs index d5d82d4..ee8214d 100644 --- a/crates/orbit/apsis-kepler/src/anomaly.rs +++ b/crates/orbit/apsis-kepler/src/anomaly.rs @@ -78,7 +78,7 @@ pub fn eccentric_from_true(true_anomaly: f64, eccentricity: f64) -> f64 { /// by Newton's method. The starting guess is the mean anomaly plus a term /// proportional to the eccentricity, which keeps the iteration stable for /// eccentricities approaching one. The iteration always terminates, and the -/// result is the value reached after at most [`MAX_ITERATIONS`] steps. +/// result is the value reached after at most a fixed number of steps. pub fn eccentric_from_mean(mean_anomaly: f64, eccentricity: f64) -> f64 { let mean = wrap_to_pi(mean_anomaly); // A first order correction to the circular guess. diff --git a/crates/physics/apsis-frames/src/iau2000/precession.rs b/crates/physics/apsis-frames/src/iau2000/precession.rs index be761bc..cb89c68 100644 --- a/crates/physics/apsis-frames/src/iau2000/precession.rs +++ b/crates/physics/apsis-frames/src/iau2000/precession.rs @@ -165,7 +165,7 @@ pub(crate) fn rotation_x(angle: f64) -> Mat3 { /// Returns a rotation of `angle` about the second axis, in radians. /// -/// The convention is the one of [`rotation_x`]. +/// The sign convention matches the other axis rotations in this module. fn rotation_y(angle: f64) -> Mat3 { let (sine, cosine) = angle.sin_cos(); Mat3::from_rows([cosine, 0.0, -sine], [0.0, 1.0, 0.0], [sine, 0.0, cosine]) @@ -173,7 +173,7 @@ fn rotation_y(angle: f64) -> Mat3 { /// Returns a rotation of `angle` about the third axis, in radians. /// -/// The convention is the one of [`rotation_x`]. +/// The sign convention matches the other axis rotations in this module. pub fn rotation_z(angle: f64) -> Mat3 { let (sine, cosine) = angle.sin_cos(); Mat3::from_rows([cosine, sine, 0.0], [-sine, cosine, 0.0], [0.0, 0.0, 1.0]) diff --git a/crates/physics/apsis-geodesy/src/lib.rs b/crates/physics/apsis-geodesy/src/lib.rs index 7534c10..0f977ab 100644 --- a/crates/physics/apsis-geodesy/src/lib.rs +++ b/crates/physics/apsis-geodesy/src/lib.rs @@ -6,7 +6,7 @@ //! differ by up to about 0.19 degrees at mid latitudes, so the distinction //! matters for pointing and ranging. //! -//! [`Wgs84`] is the ellipsoid used by GPS and by almost all satellite work. +//! [`WGS84`] is the ellipsoid used by GPS and by almost all satellite work. //! Its defining parameters are the semi-major axis and the inverse //! flattening; every other quantity is derived from those two, so the //! derived values agree with the ones published in the standard to the diff --git a/crates/rf/apsis-antenna/src/lib.rs b/crates/rf/apsis-antenna/src/lib.rs index ccdfb5c..8a4f307 100644 --- a/crates/rf/apsis-antenna/src/lib.rs +++ b/crates/rf/apsis-antenna/src/lib.rs @@ -17,7 +17,7 @@ //! uniformly illuminated circular aperture it is about minus 17.6 dB. //! //! Every function here takes or returns angles in radians and gains as -//! [`Gain`], so a result can be fed straight into a link budget. +//! [`apsis_rf::Gain`], so a result can be fed straight into a link budget. //! //! Sources: //! diff --git a/crates/sim/apsis-sim-engine/src/lib.rs b/crates/sim/apsis-sim-engine/src/lib.rs index 7360662..7ceaff0 100644 --- a/crates/sim/apsis-sim-engine/src/lib.rs +++ b/crates/sim/apsis-sim-engine/src/lib.rs @@ -13,7 +13,7 @@ //! implementation meaningful. //! //! The engine stops for one of four reasons, reported as a -//! [`StopReason`](crate::StopReason): +//! [`StopReason`]: //! the queue empties, the simulation reaches its time limit, the caller asks //! it to stop, or an event limit is reached. The last two exist so that a //! model that schedules events forever cannot run without bound.