rustdoc: document-private-items makes aliased types expansion see through private fields

[mrnossiom]

Using cargo doc --document-private-items to document private types of the current workspace exposes external types private implementation details (in this case private fields). I would expect the expansion to limit itself to public fields.

e.g.

type PrivateType = Vec<String>;

gives

---

---

Quick repo

Meta

rustc --version --verbose

rustc 1.79.0-nightly (a07f3eb43 2024-04-11)
binary: rustc
commit-hash: a07f3eb43acc5df851e15176c7081a900a30a4d7
commit-date: 2024-04-11
host: x86_64-unknown-linux-gnu
release: 1.79.0-nightly
LLVM version: 18.1.3

r? @GuillaumeGomez

[GuillaumeGomez]

I suppose it's "ok" since you used the --document-private-items option. I'll add it to the next rustdoc team meeting agenda to be confirmed by the team.

[fmease]

Rendered output for anyone wondering:

[mrnossiom]

I'll summarize the exchange I had with Guillaume on matrix.

First, the --document-private-items flag I'm talking about is the one you provide to cargo doc. cargo does not blindly pass the flag to rustdoc but only for crates you own in your current workspace. That means that when documenting your workspace with cargo doc --document-private-items. Private items, fields of your crates are shown contrary to your dependencies.

Regarding design, it seems weird to me that aliased type expansion shows private implementation details of dependencies (e.g. std for the given example). I would personally expect something like:

Case 1: Expansion of an external type with private fields

// Expanded type is `Vec`, it's external to this crate so you don't expand it
type One = Vec<String>;

Case 2: Expansion of a private type with private fields

// Private-only fields struct defined in the same crate
struct Foo<T>  { f1: T, f2: u32 }
// You fully expand the fields cause they are relevent
type Two = Foo<String>;

Case 3/4: Expansion of an external type with mixed/public fields

// In a separate crate
pub struct Bar<T> { pub f1: T, f2: u32 }
pub struct Baz<T> { pub f1: T, pub f2: u32 }

// You only expand fields defined as public
type Three = Bar<String>; // only `f1`
type Four = Baz<String>; // both `f1` and `f2`