rust-lang / rust-lang/rust

False positive `rustdoc::private_intra_doc_links` for private links to private code

Open
#145,449 3 comments 0 reactions 1 assignee View on GitHub

@lolbinarycat is already working on this.

Since Sep 19, 2025.

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

Description

I tried this code:

pub trait Foo {}

mod private_module {
    #[allow(dead_code)]
    struct PrivateType;

    pub struct OtherPrivateType;

    /// This in some way involves [`PrivateType`] and we want the link to appear when building
    /// private docs.
    impl super::Foo for OtherPrivateType {}
}

#[doc(hidden)]
pub mod __exports {
    pub use super::Foo;
    pub use super::private_module::OtherPrivateType;
}

I'm not sure exactly how the doc(hidden) module is relevant, but it is required with both exports to reproduce this (it exists in the original code for macro usage).

I expected to see this happen: no warnings when building rustdoc with/without --document-private-items

Instead, this happened:

> cargo rustdoc
 Documenting foo v0.1.0 (/tmp/scratch.rust.2025-08-15T14-51.dsf19e/foo)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.21s
   Generated target/x86_64-unknown-linux-gnu/doc/foo/index.html

> cargo rustdoc -- --document-private-items
 Documenting foo v0.1.0 (/tmp/scratch.rust.2025-08-15T14-51.dsf19e/foo)
warning: public documentation for `<unknown>` links to private item `PrivateType`
 --> src/lib.rs:9:37
  |
9 |     /// This in some way involves [`PrivateType`] and we want the link to appear when building
  |                                     ^^^^^^^^^^^ this item is private
  |
  = note: this link resolves only because you passed `--document-private-items`, but will break without
  = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default

warning: `foo` (lib doc) generated 1 warning
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.20s
   Generated target/x86_64-unknown-linux-gnu/doc/foo/index.html
Meta
> rustdoc --version --verbose
rustdoc 1.90.0-nightly (b56aaec52 2025-07-24)
binary: rustdoc
commit-hash: b56aaec52bc0fa35591a872fb4aac81f606e265c
commit-date: 2025-07-24
host: x86_64-unknown-linux-gnu
release: 1.90.0-nightly
LLVM version: 20.1.8

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.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.