docs: fix documentation for opt-in hash families - #25
Closed
tisonkun wants to merge 3 commits into
Closed
Conversation
Rustdoc cannot resolve std::io paths when hashcrew is documented without its optional std feature. This leaves broken links in every streaming family and makes documentation builds fail under -D warnings. Link the optional I/O interfaces to their standard-library documentation explicitly. This keeps the guidance available to no_std users without requiring std to compile documentation, including on bare-metal targets. Verified no_std documentation with all families enabled on Rust 1.85.0 and the existing docs.rs configuration through cargo x lint --fix.
The crate overview linked every algorithm unconditionally after families became opt-in. Even an empty-feature documentation build therefore had unresolved links, while a single-family build linked nonexistent pages. Include capability rows only when their family is enabled. Keep generic family names and example names as code so the overview remains readable in every configuration. The full linked table is still present in the all-features docs.rs build, and enabled APIs keep their local links. Verified warning-free rustdoc on Rust 1.85.0 with no features, each family alone, and all families without std. Also checked the rendered xxHash table and its link targets, plus all-family docs on thumbv7em-none-eabihf.
The lint workflow only documented all features, which kept every linked module and std in scope and hid the failures seen by local cargo doc users with the default or a single-family configuration. Check the empty configuration and each discovered family without std, then retain the all-features docs.rs build as the final generated output. Use the existing family metadata and rustdoc warning checks instead of adding tests tied to documentation strings or duplicating a feature list. Validated with cargo x lint, cargo x check, cargo x build --locked, and cargo x test, including no_std doctests and release reference comparisons.
Contributor
Author
|
False positive. |
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
Fix broken rustdoc links when hash families or
stdare disabled. Previously, documentingxxhashalone produced 32 unresolved links and failed with-D warnings. Optional I/O links now point to the standard-library documentation, and the capability table links only to enabled algorithms.Extend
cargo x lintto check the empty configuration and each family withoutstdbefore generating the full docs.rs documentation. The changes are split into three commits, each explaining the failure it addresses.Validated with
cargo x lint,cargo x check,cargo x build --locked, andcargo x test; also checked warning-free rustdoc on Rust 1.85.0 with empty, individual, and combined family configurations, and onthumbv7em-none-eabihfwithoutstd.