docs: fix 50 intra-doc warnings + gate CI on -D warnings#32
Merged
Conversation
Fixes 44 cargo-doc warnings across the workspace (50 with
--document-private-items) so the CI doc job can run with
RUSTDOCFLAGS=-D warnings without spurious failures.
Fix categories:
- Unresolved intra-doc links to FerroError variants — qualify as
crate::FerroError::* in ferrolearn-core/backend.rs (12 sites).
- Redundant explicit link targets where the label already resolves —
drop the (target) suffix in core, linear, cluster, kernel.
- Public docs linking to private items — convert to plain backticks
with prose context (ferrolearn-io ModelEnvelope/SCHEMA_VERSION,
ferrolearn-bayes MIN_OBS_VAR, ferrolearn-neighbors kneighbors_impl
+ compute_lof).
- Feature-gated module references — drop intra-doc links for the
feature-gated onnx/pmml/backend_blas modules (use backticks).
- Macro vs module name collisions — disambiguate with macro@ prefix
(model-sel param_grid).
- Function vs module name collisions — disambiguate with fn@ prefix
(covariance graphical_lasso) and trailing parens (model-sel
learning_curve/validation_curve).
- HTML-tag-like generics in private doc strings — wrap in backticks
(ferrolearn-python conversions Array2<f64> etc., ferrolearn-metrics
E[MI] formula).
- Self-relative references — Self::pairwise, Self::max_features_per_split.
CI:
- ci.yml doc job: add `RUSTDOCFLAGS: -D warnings`, drop the
follow-up-PR comment that now no longer applies.
Verified locally with:
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps \
--document-private-items
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
cargo doc, 50 with--document-private-items)RUSTDOCFLAGS=-D warningsso future regressions are caught at PR timeCloses #347.
Categories of fix
FerroError::*inferrolearn-core::backend— qualified ascrate::FerroError::*(12 sites in trait method docs).(target)suffix where the label already resolves; coverscore,linear,cluster,kernel.io::ModelEnvelope/SCHEMA_VERSION,bayes::MIN_OBS_VAR,neighbors::kneighbors_impl+compute_lof).onnx/pmml/backend_blasaren't in scope when their feature is off; dropped the intra-doc link.param_gridwithmacro@.fn@graphical_lasso;learning_curve()/validation_curve()with trailing parens.Array2<f64>etc. in backticks (python::conversions,metrics::clustering).Self::pairwise,Self::max_features_per_split.CI
.github/workflows/ci.ymldoc job now setsRUSTDOCFLAGS: -D warnings. The follow-up-PR comment that explained why warnings weren't strict has been removed.Test plan
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --document-private-items— clean locallycargo fmt --check— cleancargo clippy --workspace --all-targets -- -D warnings— clean🤖 Generated with Claude Code