Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Closed
mrnossiom opened this issue Apr 12, 2024 · 3 comments · Fixed by #124939
Closed

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

mrnossiom opened this issue Apr 12, 2024 · 3 comments · Fixed by #124939
Labels
T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@mrnossiom
Copy link
Contributor

mrnossiom commented Apr 12, 2024 •
edited
Loading

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

image

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
@rustbot rustbot added the needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. label Apr 12, 2024
@GuillaumeGomez GuillaumeGomez added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. C-bug Category: This is a bug. and removed needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. C-bug Category: This is a bug. labels Apr 12, 2024
@GuillaumeGomez
Copy link
Member

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
Copy link
Member

fmease commented Apr 13, 2024

Rendered output for anyone wondering:

image

@mrnossiom
Copy link
Contributor Author

mrnossiom commented Apr 13, 2024 •
edited
Loading

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`

@lqd lqd mentioned this issue May 9, 2024
Closed
@workingjubilee workingjubilee mentioned this issue May 9, 2024
Merged
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this issue May 11, 2024
@GuillaumeGomez
Rollup merge of rust-lang#124939 - Urgau:hide-private-fields-aliased-…
9aa585d 
…type, r=GuillaumeGomez

Always hide private fields in aliased type

This PR adds a new rustdoc pass that unconditionally always strips all private fields in aliased type, since showing them, even with `--document-private-items`, is confusing, unhelpful, and run backwards to the "Aliased type" feature, which is to show the type as it would be seen by the user.

r? `@GuillaumeGomez`
Fixes rust-lang#124938
Fixes rust-lang#123860
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this issue May 11, 2024
@GuillaumeGomez
Rollup merge of rust-lang#124939 - Urgau:hide-private-fields-aliased-…
bf8d0b8 
…type, r=GuillaumeGomez

Always hide private fields in aliased type

This PR adds a new rustdoc pass that unconditionally always strips all private fields in aliased type, since showing them, even with `--document-private-items`, is confusing, unhelpful, and run backwards to the "Aliased type" feature, which is to show the type as it would be seen by the user.

r? ``@GuillaumeGomez``
Fixes rust-lang#124938
Fixes rust-lang#123860
@bors bors closed this as completed in beef360 May 12, 2024
rust-timer added a commit to rust-lang-ci/rust that referenced this issue May 12, 2024
@rust-timer
Unrolled build for rust-lang#124939
1bbddc1 
Rollup merge of rust-lang#124939 - Urgau:hide-private-fields-aliased-type, r=GuillaumeGomez

Always hide private fields in aliased type

This PR adds a new rustdoc pass that unconditionally always strips all private fields in aliased type, since showing them, even with `--document-private-items`, is confusing, unhelpful, and run backwards to the "Aliased type" feature, which is to show the type as it would be seen by the user.

r? ```@GuillaumeGomez```
Fixes rust-lang#124938
Fixes rust-lang#123860
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Always hide private fields in aliased type Urgau/rust
4 participants
@GuillaumeGomez @fmease @mrnossiom @rustbot