Skip to content

Commit

Permalink
Auto merge of #95024 - koehlma:rustdoc-private-items, r=GuillaumeGome…
Browse files Browse the repository at this point in the history 
…z,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 #87785) when looking at the documentation makes this somewhat cumbersome.

This PR addresses the third suggestion of issue #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.
  • Loading branch information
@bors
bors committed Mar 28, 2022
2 parents 0e4524e + 1c523ba commit 2d37f38
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 3 deletions.
15 changes: 12 additions & 3 deletions src/librustdoc/html/render/print_item.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -376,17 +376,26 @@ fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[cl
let stab = myitem.stability_class(cx.tcx());
let add = if stab.is_some() { " " } else { "" };

let visibility_emoji = match myitem.visibility {
clean::Visibility::Restricted(_) => {
"<span title=\"Restricted Visibility\">&nbsp;🔒</span> "
}
_ => "",
};

let doc_value = myitem.doc_value().unwrap_or_default();
w.write_str(ITEM_TABLE_ROW_OPEN);
write!(
w,
"<div class=\"item-left {stab}{add}module-item\">\
<a class=\"{class}\" href=\"{href}\" title=\"{title}\">{name}</a>\
{unsafety_flag}\
{stab_tags}\
<a class=\"{class}\" href=\"{href}\" title=\"{title}\">{name}</a>\
{visibility_emoji}\
{unsafety_flag}\
{stab_tags}\
</div>\
<div class=\"item-right docblock-short\">{docs}</div>",
name = myitem.name.unwrap(),
visibility_emoji = visibility_emoji,
stab_tags = extra_info_tags(myitem, item, cx.tcx()),
docs = MarkdownSummaryLine(&doc_value, &myitem.links(cx)).into_string(),
class = myitem.type_(),
Expand Down
31 changes: 31 additions & 0 deletions src/test/rustdoc/visibility.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,42 +4,68 @@

#![crate_name = "foo"]

// @!has 'foo/index.html' '//a[@href="struct.FooPublic.html"]/..' 'FooPublic 🔒'
// @has 'foo/struct.FooPublic.html' '//pre' 'pub struct FooPublic'
pub struct FooPublic;
// @has 'foo/index.html' '//a[@href="struct.FooJustCrate.html"]/..' 'FooJustCrate 🔒'
// @has 'foo/struct.FooJustCrate.html' '//pre' 'pub(crate) struct FooJustCrate'
crate struct FooJustCrate;
// @has 'foo/index.html' '//a[@href="struct.FooPubCrate.html"]/..' 'FooPubCrate 🔒'
// @has 'foo/struct.FooPubCrate.html' '//pre' 'pub(crate) struct FooPubCrate'
pub(crate) struct FooPubCrate;
// @has 'foo/index.html' '//a[@href="struct.FooSelf.html"]/..' 'FooSelf 🔒'
// @has 'foo/struct.FooSelf.html' '//pre' 'pub(crate) struct FooSelf'
pub(self) struct FooSelf;
// @has 'foo/index.html' '//a[@href="struct.FooInSelf.html"]/..' 'FooInSelf 🔒'
// @has 'foo/struct.FooInSelf.html' '//pre' 'pub(crate) struct FooInSelf'
pub(in self) struct FooInSelf;
// @has 'foo/index.html' '//a[@href="struct.FooPriv.html"]/..' 'FooPriv 🔒'
// @has 'foo/struct.FooPriv.html' '//pre' 'pub(crate) struct FooPriv'
struct FooPriv;

// @!has 'foo/index.html' '//a[@href="pub_mod/index.html"]/..' 'pub_mod 🔒'
pub mod pub_mod {}

// @has 'foo/index.html' '//a[@href="pub_crate_mod/index.html"]/..' 'pub_crate_mod 🔒'
pub(crate) mod pub_crate_mod {}

// @has 'foo/index.html' '//a[@href="a/index.html"]/..' 'a 🔒'
mod a {
// @has 'foo/a/index.html' '//a[@href="struct.FooASuper.html"]/..' 'FooASuper 🔒'
// @has 'foo/a/struct.FooASuper.html' '//pre' 'pub(crate) struct FooASuper'
pub(super) struct FooASuper;
// @has 'foo/a/index.html' '//a[@href="struct.FooAInSuper.html"]/..' 'FooAInSuper 🔒'
// @has 'foo/a/struct.FooAInSuper.html' '//pre' 'pub(crate) struct FooAInSuper'
pub(in super) struct FooAInSuper;
// @has 'foo/a/index.html' '//a[@href="struct.FooAInA.html"]/..' 'FooAInA 🔒'
// @has 'foo/a/struct.FooAInA.html' '//pre' 'struct FooAInA'
// @!has 'foo/a/struct.FooAInA.html' '//pre' 'pub'
pub(in a) struct FooAInA;
// @has 'foo/a/index.html' '//a[@href="struct.FooAPriv.html"]/..' 'FooAPriv 🔒'
// @has 'foo/a/struct.FooAPriv.html' '//pre' 'struct FooAPriv'
// @!has 'foo/a/struct.FooAPriv.html' '//pre' 'pub'
struct FooAPriv;

// @has 'foo/a/index.html' '//a[@href="b/index.html"]/..' 'b 🔒'
mod b {
// @has 'foo/a/b/index.html' '//a[@href="struct.FooBSuper.html"]/..' 'FooBSuper 🔒'
// @has 'foo/a/b/struct.FooBSuper.html' '//pre' 'pub(super) struct FooBSuper'
pub(super) struct FooBSuper;
// @has 'foo/a/b/index.html' '//a[@href="struct.FooBInSuperSuper.html"]/..' 'FooBInSuperSuper 🔒'
// @has 'foo/a/b/struct.FooBInSuperSuper.html' '//pre' 'pub(crate) struct FooBInSuperSuper'
pub(in super::super) struct FooBInSuperSuper;
// @has 'foo/a/b/index.html' '//a[@href="struct.FooBInAB.html"]/..' 'FooBInAB 🔒'
// @has 'foo/a/b/struct.FooBInAB.html' '//pre' 'struct FooBInAB'
// @!has 'foo/a/b/struct.FooBInAB.html' '//pre' 'pub'
pub(in a::b) struct FooBInAB;
// @has 'foo/a/b/index.html' '//a[@href="struct.FooBPriv.html"]/..' 'FooBPriv 🔒'
// @has 'foo/a/b/struct.FooBPriv.html' '//pre' 'struct FooBPriv'
// @!has 'foo/a/b/struct.FooBPriv.html' '//pre' 'pub'
struct FooBPriv;

// @!has 'foo/a/b/index.html' '//a[@href="struct.FooBPub.html"]/..' 'FooBPub 🔒'
// @has 'foo/a/b/struct.FooBPub.html' '//pre' 'pub struct FooBPub'
pub struct FooBPub;
}
}

Expand All @@ -53,13 +79,18 @@ mod a {
//
// @has 'foo/trait.PubTrait.html' '//pre' 'fn function();'
// @!has 'foo/trait.PubTrait.html' '//pre' 'pub fn function();'
//
// @!has 'foo/index.html' '//a[@href="trait.PubTrait.html"]/..' 'PubTrait 🔒'

pub trait PubTrait {
type Type;
const CONST: usize;
fn function();
}

// @has 'foo/index.html' '//a[@href="trait.PrivTrait.html"]/..' 'PrivTrait 🔒'
trait PrivTrait {}

// @has 'foo/struct.FooPublic.html' '//h4[@class="code-header"]' 'type Type'
// @!has 'foo/struct.FooPublic.html' '//h4[@class="code-header"]' 'pub type Type'
//
Expand Down

0 comments on commit 2d37f38

Please sign in to comment.