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 currently does not distinguish between public and private items #87785

Closed
pvshvp-oss opened this issue Aug 5, 2021 · 3 comments
Closed

Rustdoc currently does not distinguish between public and private items #87785

pvshvp-oss opened this issue Aug 5, 2021 · 3 comments
Labels
A-visibility Area: Visibility / privacy C-feature-request Category: A feature request, i.e: not implemented / a PR. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@pvshvp-oss
Copy link

Rustdoc currently does not label, mark, or otherwise separate private items to distinguish them from public items, when the --document-private-items command-line argument is passed. The generated documentation hence can be confusing to the reader. I suggest enabling one or more of the below through rustdoc:

  1. Separate public and private items in the generated documentation
  2. Enable toggling the visibility of private items in the generated documentation.
  3. Label or mark private items to clearly distinguish them from public items.

This issue was prompted by rust-lang/docs.rs#304 (comment)
@inquisitivecrystal inquisitivecrystal added A-visibility Area: Visibility / privacy C-feature-request Category: A feature request, i.e: not implemented / a PR. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Aug 6, 2021
@jyn514
Copy link
Member

jyn514 commented Aug 19, 2021

@shivanandvp so, I spoke a little too quickly before, rustdoc does in fact distinguish items with different visibility, you just have to click through to the item itself instead of the module where it's listed:
image
image
image

@koehlma
Copy link
Contributor

koehlma commented Mar 16, 2022 •
edited
Loading

How about adding some transparency to the item names or would that be too subtle?

I think I would be able to contribute a PR making this happen.

@koehlma koehlma mentioned this issue Mar 16, 2022
Merged
bors added a commit to rust-lang-ci/rust that referenced this issue Mar 28, 2022
@bors
Auto merge of rust-lang#95024 - koehlma:rustdoc-private-items, r=Guil…
2d37f38 
…laumeGomez,camelid,jsha

rustdoc: add 🔒 to items with restricted visibility

This change marks items with restricted visibility with 🔒 when building with `--document-private-items`:

<img width="278" alt="Screen Shot 2022-03-20 at 23 50 24" src="https://user-images.githubusercontent.com/509209/159189513-9e4b09bb-6785-41a5-bfe2-df02f83f8641.png">

There also appears a “Restricted Visibility” tooltip when hovering over the emoji.

---

The original PR for reference:

This change makes private items slightly transparent (similar to `unstable` items in rustc):

<img width="272" alt="Screen Shot 2022-03-16 at 22 17 43" src="https://user-images.githubusercontent.com/509209/158692627-a1f6f5ec-e043-4aa2-9352-8d2b15c31c08.png">

I found myself using `--document-private-items` a lot recently because I find the documentation of private internals quite helpful when working on a larger project. However, not being able to distinguish private from public items (see rust-lang#87785) when looking at the documentation makes this somewhat cumbersome.

This PR addresses the third suggestion of issue rust-lang#87785 by marking private items typographically. It seems to me that the other suggestions are more involved but this is at least a first step.

A private item is also made slightly transparent in the path displayed in the header of a page:

<img width="467" alt="Screen Shot 2022-03-16 at 22 19 51" src="https://user-images.githubusercontent.com/509209/158692885-0bbd3417-3c0b-486f-b8ab-99c05c6fa7ca.png">

I am looking forward to feedback and suggestions.
@GuillaumeGomez
Copy link
Member

Fixed by #95024.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
A-visibility Area: Visibility / privacy C-feature-request Category: A feature request, i.e: not implemented / a PR. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@koehlma @GuillaumeGomez @pvshvp-oss @inquisitivecrystal @jyn514