private-intra-doc-links incorrectly shows error for public type alias to private wrapper type
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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