rust-lang / rust-lang/rust

private-intra-doc-links incorrectly shows error for public type alias to private wrapper type

Open
#132,952 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

pub struct WholeNumber(u32);

pub use bar::Integer;
mod foo {
    // This is private
    pub struct Signed<T>(pub T);
}

mod bar {
    /// If you want to do things, try [`Integer::do_thing()`]
    pub type Integer = crate::foo::Signed<crate::WholeNumber>;

    impl Integer {
        pub fn do_thing() {}
    }
}

Shows

warning: public documentation for `Integer` links to private item `Integer::do_thing`
  --> src/lib.rs:10:41
   |
10 |     /// If you want to do things, try [`Integer::do_thing()`]
   |                                         ^^^^^^^^^^^^^^^^^^^ this item is private
   |
   = note: this link will resolve properly if you pass `--document-private-items`
   = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default

under cargo doc.

This is (a) incorrect: Integer::do_thing() is public and accessible even if Signed isn't and (b) misleading: the problem is not the publicness of do_thing() but rather the fact that Signed is inaccessible. The diagnostic is confusing and doesn't help fix the problem.

I think this should probably be considered a false positive, but either way, the diagnostic ought to be be clearer about what needs to be fixed here.

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 warning with the shown example under cargo doc, then trace the rustdoc handling of private_intra_doc_links and public type aliases. Compare the resolved visibility of Integer::do_thing() with the private Signed wrapper. Done means the diagnostic no longer falsely identifies the method as private and clearly explains any remaining issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
compilers, 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.