bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Rollup merge of #80368 - camelid:rustdoc-succinct-vis, r=jyn514

Browse source 
rustdoc: Render visibilities succinctly

Fixes #79139.

r? `@jyn514`
This commit is contained in:
Dylan DPC 2020-12-31 22:20:49 +01:00 • committed by GitHub
commit 7d247c9246
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 136 additions and 97 deletions
Download patch file Download diff file Expand all files Collapse all files

5
src/librustdoc/clean/mod.rs
View file

@ -2325,18 +2325,19 @@ impl Clean<Item> for (&hir::MacroDef<'_>, Option<Symbol>) {
)
} else {
let vis = item.vis.clean(cx);
let def_id = cx.tcx.hir().local_def_id(item.hir_id).to_def_id();
if matchers.len() <= 1 {
format!(
"{}macro {}{} {{\n ...\n}}",
vis.print_with_space(cx.tcx),
vis.print_with_space(cx.tcx, def_id),
name,
matchers.iter().map(|span| span.to_src(cx)).collect::<String>(),
)
} else {
format!(
"{}macro {} {{\n{}}}",
vis.print_with_space(cx.tcx),
vis.print_with_space(cx.tcx, def_id),
name,
matchers
.iter()

23
src/librustdoc/clean/utils.rs
View file

@ -14,7 +14,7 @@ use rustc_hir::def::{DefKind, Res};
use rustc_hir::def_id::{DefId, LOCAL_CRATE};
use rustc_middle::mir::interpret::ConstValue;
use rustc_middle::ty::subst::{GenericArgKind, SubstsRef};
use rustc_middle::ty::{self, DefIdTree, Ty};
use rustc_middle::ty::{self, DefIdTree, Ty, TyCtxt};
use rustc_span::symbol::{kw, sym, Symbol};
use std::mem;
@ -623,3 +623,24 @@ where
*cx.impl_trait_bounds.borrow_mut() = old_bounds;
r
}
/// Find the nearest parent module of a [`DefId`].
///
/// **Panics if the item it belongs to [is fake][Item::is_fake].**
crate fn find_nearest_parent_module(tcx: TyCtxt<'_>, def_id: DefId) -> Option<DefId> {
if def_id.is_top_level_module() {
// The crate root has no parent. Use it as the root instead.
Some(def_id)
} else {
let mut current = def_id;
// The immediate parent might not always be a module.
// Find the first parent which is.
while let Some(parent) = tcx.parent(current) {
if tcx.def_kind(parent) == DefKind::Mod {
return Some(parent);
}
current = parent;
}
None
}
}

38
src/librustdoc/html/format.rs
View file

@ -15,7 +15,7 @@ use rustc_middle::ty::TyCtxt;
use rustc_span::def_id::{DefId, CRATE_DEF_INDEX};
use rustc_target::spec::abi::Abi;
use crate::clean::{self, PrimitiveType};
use crate::clean::{self, utils::find_nearest_parent_module, PrimitiveType};
use crate::formats::cache::cache;
use crate::formats::item_type::ItemType;
use crate::html::escape::Escape;
@ -1085,22 +1085,43 @@ impl Function<'_> {
}
impl clean::Visibility {
crate fn print_with_space<'tcx>(self, tcx: TyCtxt<'tcx>) -> impl fmt::Display + 'tcx {
crate fn print_with_space<'tcx>(
self,
tcx: TyCtxt<'tcx>,
item_did: DefId,
) -> impl fmt::Display + 'tcx {
use rustc_span::symbol::kw;
display_fn(move |f| match self {
clean::Public => f.write_str("pub "),
clean::Inherited => Ok(()),
clean::Visibility::Restricted(did) if did.index == CRATE_DEF_INDEX => {
clean::Visibility::Restricted(vis_did) => {
// FIXME(camelid): This may not work correctly if `item_did` is a module.
// However, rustdoc currently never displays a module's
// visibility, so it shouldn't matter.
let parent_module = find_nearest_parent_module(tcx, item_did);
if vis_did.index == CRATE_DEF_INDEX {
write!(f, "pub(crate) ")
}
clean::Visibility::Restricted(did) => {
} else if parent_module == Some(vis_did) {
// `pub(in foo)` where `foo` is the parent module
// is the same as no visibility modifier
Ok(())
} else if parent_module
.map(|parent| find_nearest_parent_module(tcx, parent))
.flatten()
== Some(vis_did)
{
write!(f, "pub(super) ")
} else {
f.write_str("pub(")?;
let path = tcx.def_path(did);
let path = tcx.def_path(vis_did);
debug!("path={:?}", path);
let first_name =
path.data[0].data.get_opt_name().expect("modules are always named");
if path.data.len() != 1 || (first_name != kw::SelfLower && first_name != kw::Super)
if path.data.len() != 1
|| (first_name != kw::SelfLower && first_name != kw::Super)
{
f.write_str("in ")?;
}
@ -1109,9 +1130,10 @@ impl clean::Visibility {
for seg in &path.data[..path.data.len() - 1] {
write!(f, "{}::", seg.data.get_opt_name().unwrap())?;
}
let path = anchor(did, &last_name.as_str()).to_string();
let path = anchor(vis_did, &last_name.as_str()).to_string();
write!(f, "{}) ", path)
}
}
})
}
}

41
src/librustdoc/html/render/mod.rs
View file

@ -2157,14 +2157,14 @@ fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[cl
Some(ref src) => write!(
w,
"<tr><td><code>{}extern crate {} as {};",
myitem.visibility.print_with_space(cx.tcx()),
myitem.visibility.print_with_space(cx.tcx(), myitem.def_id),
anchor(myitem.def_id, &*src.as_str()),
name
),
None => write!(
w,
"<tr><td><code>{}extern crate {};",
myitem.visibility.print_with_space(cx.tcx()),
myitem.visibility.print_with_space(cx.tcx(), myitem.def_id),
anchor(myitem.def_id, &*name.as_str())
),
}
@ -2175,7 +2175,7 @@ fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[cl
write!(
w,
"<tr><td><code>{}{}</code></td></tr>",
myitem.visibility.print_with_space(cx.tcx()),
myitem.visibility.print_with_space(cx.tcx(), myitem.def_id),
import.print()
);
}
@ -2392,7 +2392,7 @@ fn item_constant(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, c: &clean::
write!(
w,
"{vis}const {name}: {typ}",
vis = it.visibility.print_with_space(cx.tcx()),
vis = it.visibility.print_with_space(cx.tcx(), it.def_id),
name = it.name.as_ref().unwrap(),
typ = c.type_.print(),
);
@ -2426,7 +2426,7 @@ fn item_static(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::St
write!(
w,
"{vis}static {mutability}{name}: {typ}</pre>",
vis = it.visibility.print_with_space(cx.tcx()),
vis = it.visibility.print_with_space(cx.tcx(), it.def_id),
mutability = s.mutability.print_with_space(),
name = it.name.as_ref().unwrap(),
typ = s.type_.print()
@ -2437,7 +2437,7 @@ fn item_static(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::St
fn item_function(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, f: &clean::Function) {
let header_len = format!(
"{}{}{}{}{:#}fn {}{:#}",
it.visibility.print_with_space(cx.tcx()),
it.visibility.print_with_space(cx.tcx(), it.def_id),
f.header.constness.print_with_space(),
f.header.asyncness.print_with_space(),
f.header.unsafety.print_with_space(),
@ -2452,7 +2452,7 @@ fn item_function(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, f: &clean::
w,
"{vis}{constness}{asyncness}{unsafety}{abi}fn \
{name}{generics}{decl}{spotlight}{where_clause}</pre>",
vis = it.visibility.print_with_space(cx.tcx()),
vis = it.visibility.print_with_space(cx.tcx(), it.def_id),
constness = f.header.constness.print_with_space(),
asyncness = f.header.asyncness.print_with_space(),
unsafety = f.header.unsafety.print_with_space(),
@ -2578,7 +2578,7 @@ fn item_trait(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::Tra
write!(
w,
"{}{}{}trait {}{}{}",
it.visibility.print_with_space(cx.tcx()),
it.visibility.print_with_space(cx.tcx(), it.def_id),
t.unsafety.print_with_space(),
if t.is_auto { "auto " } else { "" },
it.name.as_ref().unwrap(),
@ -2896,7 +2896,7 @@ fn assoc_const(
w,
"{}{}const <a href=\"{}\" class=\"constant\"><b>{}</b></a>: {}",
extra,
it.visibility.print_with_space(cx.tcx()),
it.visibility.print_with_space(cx.tcx(), it.def_id),
naive_assoc_href(it, link),
it.name.as_ref().unwrap(),
ty.print()
@ -3015,7 +3015,7 @@ fn render_assoc_item(
};
let mut header_len = format!(
"{}{}{}{}{}{:#}fn {}{:#}",
meth.visibility.print_with_space(cx.tcx()),
meth.visibility.print_with_space(cx.tcx(), meth.def_id),
header.constness.print_with_space(),
header.asyncness.print_with_space(),
header.unsafety.print_with_space(),
@ -3037,7 +3037,7 @@ fn render_assoc_item(
"{}{}{}{}{}{}{}fn <a href=\"{href}\" class=\"fnname\">{name}</a>\
{generics}{decl}{spotlight}{where_clause}",
if parent == ItemType::Trait { " " } else { "" },
meth.visibility.print_with_space(cx.tcx()),
meth.visibility.print_with_space(cx.tcx(), meth.def_id),
header.constness.print_with_space(),
header.asyncness.print_with_space(),
header.unsafety.print_with_space(),
@ -3189,7 +3189,7 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum
write!(
w,
"{}enum {}{}{}",
it.visibility.print_with_space(cx.tcx()),
it.visibility.print_with_space(cx.tcx(), it.def_id),
it.name.as_ref().unwrap(),
e.generics.print(),
WhereClause { gens: &e.generics, indent: 0, end_newline: true }
@ -3365,7 +3365,7 @@ fn render_struct(
write!(
w,
"{}{}{}",
it.visibility.print_with_space(cx.tcx()),
it.visibility.print_with_space(cx.tcx(), it.def_id),
if structhead { "struct " } else { "" },
it.name.as_ref().unwrap()
);
@ -3385,7 +3385,7 @@ fn render_struct(
w,
"\n{} {}{}: {},",
tab,
field.visibility.print_with_space(cx.tcx()),
field.visibility.print_with_space(cx.tcx(), field.def_id),
field.name.as_ref().unwrap(),
ty.print()
);
@ -3414,7 +3414,12 @@ fn render_struct(
match *field.kind {
clean::StrippedItem(box clean::StructFieldItem(..)) => write!(w, "_"),
clean::StructFieldItem(ref ty) => {
write!(w, "{}{}", field.visibility.print_with_space(cx.tcx()), ty.print())
write!(
w,
"{}{}",
field.visibility.print_with_space(cx.tcx(), field.def_id),
ty.print()
)
}
_ => unreachable!(),
}
@ -3447,7 +3452,7 @@ fn render_union(
write!(
w,
"{}{}{}",
it.visibility.print_with_space(cx.tcx()),
it.visibility.print_with_space(cx.tcx(), it.def_id),
if structhead { "union " } else { "" },
it.name.as_ref().unwrap()
);
@ -3462,7 +3467,7 @@ fn render_union(
write!(
w,
" {}{}: {},\n{}",
field.visibility.print_with_space(cx.tcx()),
field.visibility.print_with_space(cx.tcx(), field.def_id),
field.name.as_ref().unwrap(),
ty.print(),
tab
@ -4101,7 +4106,7 @@ fn item_foreign_type(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, cache:
write!(
w,
" {}type {};\n}}</pre>",
it.visibility.print_with_space(cx.tcx()),
it.visibility.print_with_space(cx.tcx(), it.def_id),
it.name.as_ref().unwrap(),
);

26
src/librustdoc/passes/collect_intra_doc_links.rs
View file

@ -31,7 +31,7 @@ use std::convert::{TryFrom, TryInto};
use std::mem;
use std::ops::Range;
use crate::clean::{self, Crate, Item, ItemLink, PrimitiveType};
use crate::clean::{self, utils::find_nearest_parent_module, Crate, Item, ItemLink, PrimitiveType};
use crate::core::DocContext;
use crate::fold::DocFolder;
use crate::html::markdown::markdown_links;
@ -830,31 +830,9 @@ impl<'a, 'tcx> DocFolder for LinkCollector<'a, 'tcx> {
use rustc_middle::ty::DefIdTree;
let parent_node = if item.is_fake() {
// FIXME: is this correct?
None
// If we're documenting the crate root itself, it has no parent. Use the root instead.
} else if item.def_id.is_top_level_module() {
Some(item.def_id)
} else {
let mut current = item.def_id;
// The immediate parent might not always be a module.
// Find the first parent which is.
loop {
if let Some(parent) = self.cx.tcx.parent(current) {
if self.cx.tcx.def_kind(parent) == DefKind::Mod {
break Some(parent);
}
current = parent;
} else {
debug!(
"{:?} has no parent (kind={:?}, original was {:?})",
current,
self.cx.tcx.def_kind(current),
item.def_id
);
break None;
}
}
find_nearest_parent_module(self.cx.tcx, item.def_id)
};
if parent_node.is_some() {

32
src/test/rustdoc/pub-restricted.rs
View file

@ -1,32 +0,0 @@
// compile-flags: --document-private-items
#![feature(crate_visibility_modifier)]
#![crate_name = "foo"]
// @has 'foo/struct.FooPublic.html' '//pre' 'pub struct FooPublic'
pub struct FooPublic;
// @has 'foo/struct.FooJustCrate.html' '//pre' 'pub(crate) struct FooJustCrate'
crate struct FooJustCrate;
// @has 'foo/struct.FooPubCrate.html' '//pre' 'pub(crate) struct FooPubCrate'
pub(crate) struct FooPubCrate;
// @has 'foo/struct.FooSelf.html' '//pre' 'pub(crate) struct FooSelf'
pub(self) struct FooSelf;
// @has 'foo/struct.FooInSelf.html' '//pre' 'pub(crate) struct FooInSelf'
pub(in self) struct FooInSelf;
mod a {
// @has 'foo/a/struct.FooSuper.html' '//pre' 'pub(crate) struct FooSuper'
pub(super) struct FooSuper;
// @has 'foo/a/struct.FooInSuper.html' '//pre' 'pub(crate) struct FooInSuper'
pub(in super) struct FooInSuper;
// @has 'foo/a/struct.FooInA.html' '//pre' 'pub(in a) struct FooInA'
pub(in a) struct FooInA;
mod b {
// @has 'foo/a/b/struct.FooInSelfSuperB.html' '//pre' 'pub(in a::b) struct FooInSelfSuperB'
pub(in a::b) struct FooInSelfSuperB;
// @has 'foo/a/b/struct.FooInSuperSuper.html' '//pre' 'pub(crate) struct FooInSuperSuper'
pub(in super::super) struct FooInSuperSuper;
// @has 'foo/a/b/struct.FooInAB.html' '//pre' 'pub(in a::b) struct FooInAB'
pub(in a::b) struct FooInAB;
}
}

44
src/test/rustdoc/visibility.rs Normal file
View file

@ -0,0 +1,44 @@
// compile-flags: --document-private-items
#![feature(crate_visibility_modifier)]
#![crate_name = "foo"]
// @has 'foo/struct.FooPublic.html' '//pre' 'pub struct FooPublic'
pub struct FooPublic;
// @has 'foo/struct.FooJustCrate.html' '//pre' 'pub(crate) struct FooJustCrate'
crate struct FooJustCrate;
// @has 'foo/struct.FooPubCrate.html' '//pre' 'pub(crate) struct FooPubCrate'
pub(crate) struct FooPubCrate;
// @has 'foo/struct.FooSelf.html' '//pre' 'pub(crate) struct FooSelf'
pub(self) struct FooSelf;
// @has 'foo/struct.FooInSelf.html' '//pre' 'pub(crate) struct FooInSelf'
pub(in self) struct FooInSelf;
// @has 'foo/struct.FooPriv.html' '//pre' 'pub(crate) struct FooPriv'
struct FooPriv;
mod a {
// @has 'foo/a/struct.FooASuper.html' '//pre' 'pub(crate) struct FooASuper'
pub(super) struct FooASuper;
// @has 'foo/a/struct.FooAInSuper.html' '//pre' 'pub(crate) struct FooAInSuper'
pub(in super) struct FooAInSuper;
// @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/struct.FooAPriv.html' '//pre' 'struct FooAPriv'
// @!has 'foo/a/struct.FooAPriv.html' '//pre' 'pub'
struct FooAPriv;
mod b {
// @has 'foo/a/b/struct.FooBSuper.html' '//pre' 'pub(super) struct FooBSuper'
pub(super) struct FooBSuper;
// @has 'foo/a/b/struct.FooBInSuperSuper.html' '//pre' 'pub(crate) struct FooBInSuperSuper'
pub(in super::super) struct FooBInSuperSuper;
// @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/struct.FooBPriv.html' '//pre' 'struct FooBPriv'
// @!has 'foo/a/b/struct.FooBPriv.html' '//pre' 'pub'
struct FooBPriv;
}
}