Skip to content

Conversation

@clarfonthey
Copy link
Contributor

@clarfonthey clarfonthey commented Dec 18, 2025

A lot of code existed before rustdoc's intra-doc links existed, and this is reflected by the fact that the code mixes both styles of links throughout. This PR explicitly goes through all the doc links and fixes them to the new style.

Worthy notes:

  1. In order to properly link the std crate when necessary (e.g. RandomState), the #![no_std] in the crate is replaced with #![cfg_attr(not(doc), no_std]. Under pretty much all cases except rustdoc working correctly on newer versions of Rust, this should not affect anything, but it's worth pointing out.
  2. Links to std::collections::hash_map::RandomState are replaced with std::hash::RandomState in docs only. Tests still reference the old path. While this will not work on the MSRV, it's better to recommend this path in documentation since people reading the documentation will likely be using newer versions of Rust, and anyone using earlier versions will still find the old path if they search for it in rustdoc.
  3. Explicit links to the reference are still left in, since there's no standard way to mention them via rustdoc. (yet!)
  4. This will also let people view documentation locally when browsing the crate in its entirety, since external crates like rayon can be documented locally instead of always linking to external versions.

@Amanieu
Copy link
Member

Amanieu commented Dec 21, 2025

Is there a lint that we can enable to check for broken doc links?

@cuviper
Copy link
Member

cuviper commented Dec 21, 2025

Yes, rustdoc::broken_intra_doc_links -- which will also need a cargo doc run in ci.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants