rust-lang / rust-lang/rust

Rustdoc links are broken when glob reexporting items from a `doc(hidden)` module in another crate.

Open
#127,445 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-cross-crate-reexports A-intra-doc-links A-rustdoc-ui C-bug T-rustdoc
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

Rustdoc silently (no warnings) generates broken links when the item being linked to is glob-reexported from a module with the #[doc(hidden)] attribute that is from a different crate. This happens regardless of which crate the link is written in.

To reproduce, run cargo doc on two crates foo and bar with the following contents:

// foo/src/lib.rs
#[doc(hidden)]
pub mod hidden_module {
    /// [`FooOne`] [`FooTwo`] [`FooThree`]
    pub struct FooOne;
    pub struct FooTwo;
    pub struct FooThree;
}
// bar/src/lib.rs
pub use foo::hidden_module::{FooTwo, *};

/// [`FooOne`] [`FooTwo`] [`FooThree`]
pub struct Bar;

The links to FooOne and FooThree are broken as if they were unknown names, even though rustdoc emits no warnings about them like it usually does for broken links, and the documentation is otherwise functional.

Meta

rustc --version --verbose:

rustc 1.79.0 (129f3b996 2024-06-10)
binary: rustc
commit-hash: 129f3b9964af4d4a709d1383930ade12dfe7c081
commit-date: 2024-06-10
host: x86_64-apple-darwin
release: 1.79.0
LLVM version: 18.1.7

Also reproduces on nightly.

@rustbot label +T-rustdoc

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the issue with the two-crate examples in foo/src/lib.rs and bar/src/lib.rs, starting by running cargo doc and checking the generated links. Read the rustdoc link-resolution behavior for glob reexports from a doc(hidden) module in another crate. Done means FooOne, FooTwo, and FooThree links resolve correctly and the reproduction no longer silently produces broken links.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.