Skip to content

rustdoc: Hide item contents, not items #83337

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

Merged
merged 16 commits into from
Apr 16, 2021
Merged

rustdoc: Hide item contents, not items #83337

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
c96f86d
rustdoc: Stop hiding entire item declarations
Manishearth Mar 21, 2021
71c52ac
rustdoc: hide variants of enums > 5
Manishearth Mar 21, 2021
f146b97
rustdoc: hide fields of structs/unions > 5
Manishearth Mar 21, 2021
173cbec
rustdoc: smartly hide associated items of traits if there are too man…
Manishearth Mar 21, 2021
256e594
rustdoc: Add setting for hiding large items
Manishearth Mar 21, 2021
e2f59f4
Update src/librustdoc/html/render/print_item.rs
Manishearth Mar 22, 2021
846a4e9
Update src/librustdoc/html/render/print_item.rs
Manishearth Mar 22, 2021
def144c
Improve CSS for "hide contents, not items"
jsha Mar 27, 2021
8e9882d
Add css classes
Manishearth Mar 28, 2021
01afa07
should_hide_fields > 12
Manishearth Apr 12, 2021
b40bd5a
Add test for item hiding
Manishearth Apr 12, 2021
97cd30d
Wrap toggle_open()
Manishearth Apr 12, 2021
05d1e72
& -> &&
Manishearth Apr 12, 2021
942ed31
Move color to themes
Manishearth Apr 12, 2021
5c2820b
+ignore-tidy-filelength
Manishearth Apr 12, 2021
55b2944
Update attribute tests
Manishearth Apr 13, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 26 additions & 38 deletions src/librustdoc/html/render/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,6 @@ use std::path::PathBuf;
use std::str;
use std::string::ToString;

use itertools::Itertools;
use rustc_ast_pretty::pprust;
use rustc_attr::{Deprecation, StabilityLevel};
use rustc_data_structures::fx::FxHashSet;
Expand Down Expand Up @@ -486,18 +485,7 @@ fn settings(root_path: &str, suffix: &str, themes: &[StylePath]) -> Result<Strin
],
)
.into(),
(
"Auto-hide item declarations",
vec![
("auto-hide-struct", "Auto-hide structs declaration", true),
("auto-hide-enum", "Auto-hide enums declaration", false),
("auto-hide-union", "Auto-hide unions declaration", true),
("auto-hide-trait", "Auto-hide traits declaration", true),
("auto-hide-macro", "Auto-hide macros declaration", false),
],
)
.into(),
("auto-hide-attributes", "Auto-hide item attributes.", true).into(),
("auto-hide-large-items", "Auto-hide item contents for large items.", true).into(),
("auto-hide-method-docs", "Auto-hide item methods' documentation", false).into(),
("auto-hide-trait-implementations", "Auto-hide trait implementation documentation", true)
.into(),
Expand Down Expand Up @@ -946,19 +934,21 @@ fn render_assoc_item(
+ name.as_str().len()
+ generics_len;

let (indent, end_newline) = if parent == ItemType::Trait {
let (indent, indent_str, end_newline) = if parent == ItemType::Trait {
header_len += 4;
(4, false)
let indent_str = " ";
render_attributes_in_pre(w, meth, indent_str);
(4, indent_str, false)
} else {
(0, true)
render_attributes_in_code(w, meth);
(0, "", true)
};
render_attributes(w, meth, false);
w.reserve(header_len + "<a href=\"\" class=\"fnname\">{".len() + "</a>".len());
write!(
w,
"{}{}{}{}{}{}{}fn <a href=\"{href}\" class=\"fnname\">{name}</a>\
{generics}{decl}{notable_traits}{where_clause}",
if parent == ItemType::Trait { " " } else { "" },
indent_str,
vis,
constness,
asyncness,
Expand Down Expand Up @@ -1014,35 +1004,33 @@ const ALLOWED_ATTRIBUTES: &[Symbol] = &[
sym::non_exhaustive,
];

// The `top` parameter is used when generating the item declaration to ensure it doesn't have a
// left padding. For example:
//
// #[foo] <----- "top" attribute
// struct Foo {
// #[bar] <---- not "top" attribute
// bar: usize,
// }
fn render_attributes(w: &mut Buffer, it: &clean::Item, top: bool) {
let attrs = it
.attrs
fn attributes(it: &clean::Item) -> Vec<String> {
it.attrs
.other_attrs
.iter()
.filter_map(|attr| {
if ALLOWED_ATTRIBUTES.contains(&attr.name_or_empty()) {
Some(pprust::attribute_to_string(&attr))
Some(pprust::attribute_to_string(&attr).replace("\n", "").replace(" ", " "))
} else {
None
}
})
.join("\n");
.collect()
}

if !attrs.is_empty() {
write!(
w,
"<span class=\"docblock attributes{}\">{}</span>",
if top { " top-attr" } else { "" },
&attrs
);
// When an attribute is rendered inside a `<pre>` tag, it is formatted using
// a whitespace prefix and newline.
fn render_attributes_in_pre(w: &mut Buffer, it: &clean::Item, prefix: &str) {
for a in attributes(it) {
write!(w, "{}{}\n", prefix, a);
}
}

// When an attribute is rendered inside a <code> tag, it is formatted using
// a div to produce a newline after it.
fn render_attributes_in_code(w: &mut Buffer, it: &clean::Item) {
for a in attributes(it) {
write!(w, "<div class=\"code-attribute\">{}</div>", a);
}
}

Expand Down
99 changes: 83 additions & 16 deletions src/librustdoc/html/render/print_item.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ use rustc_span::symbol::{kw, sym, Symbol};

use super::{
collect_paths_for_type, document, ensure_trailing_slash, item_ty_to_strs, notable_traits_decl,
render_assoc_item, render_assoc_items, render_attributes, render_impl,
render_stability_since_raw, write_srclink, AssocItemLink, Context,
render_assoc_item, render_assoc_items, render_attributes_in_code, render_attributes_in_pre,
render_impl, render_stability_since_raw, write_srclink, AssocItemLink, Context,
};
use crate::clean::{self, GetDefId};
use crate::formats::cache::Cache;
Expand Down Expand Up @@ -131,6 +131,26 @@ pub(super) fn print_item(cx: &Context<'_>, item: &clean::Item, buf: &mut Buffer)
}
}

/// For large structs, enums, unions, etc, determine whether to hide their fields
fn should_hide_fields(n_fields: usize) -> bool {
n_fields > 12
}

fn toggle_open(w: &mut Buffer, text: &str) {
write!(
w,
"<details class=\"rustdoc-toggle type-contents-toggle\">\
<summary class=\"hideme\">\
<span>Show {}</span>\
</summary>",
text
);
}

fn toggle_close(w: &mut Buffer) {
w.write_str("</details>");
}

fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[clean::Item]) {
document(w, cx, item, None);

Expand Down Expand Up @@ -377,7 +397,7 @@ fn item_function(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, f: &clean::
)
.len();
w.write_str("<pre class=\"rust fn\">");
render_attributes(w, it, false);
render_attributes_in_pre(w, it, "");
write!(
w,
"{vis}{constness}{asyncness}{unsafety}{abi}fn \
Expand Down Expand Up @@ -406,7 +426,7 @@ fn item_trait(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::Tra
// Output the trait definition
wrap_into_docblock(w, |w| {
w.write_str("<pre class=\"rust trait\">");
render_attributes(w, it, true);
render_attributes_in_pre(w, it, "");
write!(
w,
"{}{}{}trait {}{}{}",
Expand All @@ -429,17 +449,36 @@ fn item_trait(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::Tra
} else {
// FIXME: we should be using a derived_id for the Anchors here
w.write_str("{\n");
let mut toggle = false;

// If there are too many associated types, hide _everything_
if should_hide_fields(types.len()) {
toggle = true;
toggle_open(w, "associated items");
}
for t in &types {
render_assoc_item(w, t, AssocItemLink::Anchor(None), ItemType::Trait, cx);
w.write_str(";\n");
}
// If there are too many associated constants, hide everything after them
// We also do this if the types + consts is large because otherwise we could
// render a bunch of types and _then_ a bunch of consts just because both were
// _just_ under the limit
if !toggle && should_hide_fields(types.len() + consts.len()) {
toggle = true;
toggle_open(w, "associated constants and methods");
}
if !types.is_empty() && !consts.is_empty() {
w.write_str("\n");
}
for t in &consts {
render_assoc_item(w, t, AssocItemLink::Anchor(None), ItemType::Trait, cx);
w.write_str(";\n");
}
if !toggle && should_hide_fields(required.len() + provided.len()) {
toggle = true;
toggle_open(w, "methods");
}
if !consts.is_empty() && !required.is_empty() {
w.write_str("\n");
}
Expand Down Expand Up @@ -470,6 +509,9 @@ fn item_trait(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::Tra
w.write_str("<div class=\"item-spacer\"></div>");
}
}
if toggle {
toggle_close(w);
}
w.write_str("}");
}
w.write_str("</pre>")
Expand Down Expand Up @@ -693,7 +735,7 @@ fn item_trait(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::Tra

fn item_trait_alias(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::TraitAlias) {
w.write_str("<pre class=\"rust trait-alias\">");
render_attributes(w, it, false);
render_attributes_in_pre(w, it, "");
write!(
w,
"trait {}{}{} = {};</pre>",
Expand All @@ -714,7 +756,7 @@ fn item_trait_alias(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clea

fn item_opaque_ty(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::OpaqueTy) {
w.write_str("<pre class=\"rust opaque\">");
render_attributes(w, it, false);
render_attributes_in_pre(w, it, "");
write!(
w,
"type {}{}{where_clause} = impl {bounds};</pre>",
Expand All @@ -735,7 +777,7 @@ fn item_opaque_ty(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean:

fn item_typedef(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::Typedef) {
w.write_str("<pre class=\"rust typedef\">");
render_attributes(w, it, false);
render_attributes_in_pre(w, it, "");
write!(
w,
"type {}{}{where_clause} = {type_};</pre>",
Expand All @@ -757,7 +799,7 @@ fn item_typedef(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::T
fn item_union(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::Union) {
wrap_into_docblock(w, |w| {
w.write_str("<pre class=\"rust union\">");
render_attributes(w, it, true);
render_attributes_in_pre(w, it, "");
render_union(w, it, Some(&s.generics), &s.fields, "", true, cx);
w.write_str("</pre>")
});
Expand Down Expand Up @@ -803,7 +845,7 @@ fn item_union(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::Uni
fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum) {
wrap_into_docblock(w, |w| {
w.write_str("<pre class=\"rust enum\">");
render_attributes(w, it, true);
render_attributes_in_pre(w, it, "");
write!(
w,
"{}enum {}{}{}",
Expand All @@ -816,6 +858,10 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum
w.write_str(" {}");
} else {
w.write_str(" {\n");
let toggle = should_hide_fields(e.variants.len());
if toggle {
toggle_open(w, "variants");
}
for v in &e.variants {
w.write_str(" ");
let name = v.name.as_ref().unwrap();
Expand Down Expand Up @@ -844,6 +890,9 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum
if e.variants_stripped {
w.write_str(" // some variants omitted\n");
}
if toggle {
toggle_close(w);
}
w.write_str("}");
}
w.write_str("</pre>")
Expand Down Expand Up @@ -976,7 +1025,7 @@ fn item_primitive(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item) {

fn item_constant(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, c: &clean::Constant) {
w.write_str("<pre class=\"rust const\">");
render_attributes(w, it, false);
render_attributes_in_code(w, it);

write!(
w,
Expand Down Expand Up @@ -1015,7 +1064,7 @@ fn item_constant(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, c: &clean::
fn item_struct(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::Struct) {
wrap_into_docblock(w, |w| {
w.write_str("<pre class=\"rust struct\">");
render_attributes(w, it, true);
render_attributes_in_code(w, it);
render_struct(w, it, Some(&s.generics), s.struct_type, &s.fields, "", true, cx);
w.write_str("</pre>")
});
Expand Down Expand Up @@ -1064,7 +1113,7 @@ fn item_struct(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::St

fn item_static(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::Static) {
w.write_str("<pre class=\"rust static\">");
render_attributes(w, it, false);
render_attributes_in_code(w, it);
write!(
w,
"{vis}static {mutability}{name}: {typ}</pre>",
Expand All @@ -1078,7 +1127,7 @@ fn item_static(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::St

fn item_foreign_type(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item) {
w.write_str("<pre class=\"rust foreigntype\">extern {\n");
render_attributes(w, it, false);
render_attributes_in_code(w, it);
write!(
w,
" {}type {};\n}}</pre>",
Expand Down Expand Up @@ -1171,7 +1220,7 @@ fn wrap_into_docblock<F>(w: &mut Buffer, f: F)
where
F: FnOnce(&mut Buffer),
{
w.write_str("<div class=\"docblock type-decl hidden-by-usual-hider\">");
w.write_str("<div class=\"docblock type-decl\">");
f(w);
w.write_str("</div>")
}
Expand Down Expand Up @@ -1261,6 +1310,13 @@ fn render_union(
}

write!(w, " {{\n{}", tab);
let count_fields =
fields.iter().filter(|f| matches!(*f.kind, clean::StructFieldItem(..))).count();
let toggle = should_hide_fields(count_fields);
if toggle {
toggle_open(w, "fields");
}

for field in fields {
if let clean::StructFieldItem(ref ty) = *field.kind {
write!(
Expand All @@ -1277,6 +1333,9 @@ fn render_union(
if it.has_stripped_fields().unwrap() {
write!(w, " // some fields omitted\n{}", tab);
}
if toggle {
toggle_close(w);
}
w.write_str("}");
}

Expand Down Expand Up @@ -1305,8 +1364,14 @@ fn render_struct(
if let Some(g) = g {
write!(w, "{}", print_where_clause(g, cx.cache(), cx.tcx(), 0, true),)
}
let mut has_visible_fields = false;
w.write_str(" {");
let count_fields =
fields.iter().filter(|f| matches!(*f.kind, clean::StructFieldItem(..))).count();
let has_visible_fields = count_fields > 0;
let toggle = should_hide_fields(count_fields);
if toggle {
toggle_open(w, "fields");
Copy link
Member

@GuillaumeGomez GuillaumeGomez Mar 22, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking at the code, I'd feel much better if we handled it using a closure like it was suggested. It seems very easy to forget... :-/

Copy link
Member Author

@Manishearth Manishearth Mar 22, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it's possible to have a closure for more complex things like the trait. I could use a drop guard so that it ICEs instead, but that's about it.

Copy link
Member

@GuillaumeGomez GuillaumeGomez Mar 22, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's preventing to have something like:

fn wrap_with_toggle<T, E, F: FnOnce() -> Result<T, E>>(f: F) -> Result<T, E> {
   // toggle_open code
  let ret = f()?;
  // toggle_close code
  ret
}

? I might miss something obvious here. :-/

Copy link
Member Author

@Manishearth Manishearth Mar 23, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Look at the trait code; it calls toggle_open at three different points, and toggle_close once.

Again, I tried this, it was too ugly and even more confusing, so I decided not to. I don't think this is too bad. We could add a destructor bomb but honestly we're using this a couple times and shouldn't have to yet. I'd rather get the entire toggle stuff revamped first.

}
for field in fields {
if let clean::StructFieldItem(ref ty) = *field.kind {
write!(
Expand All @@ -1317,7 +1382,6 @@ fn render_struct(
field.name.as_ref().unwrap(),
ty.print(cx.cache(), cx.tcx()),
);
has_visible_fields = true;
}
}

Expand All @@ -1331,6 +1395,9 @@ fn render_struct(
// `{ /* fields omitted */ }` to save space.
write!(w, " /* fields omitted */ ");
}
if toggle {
toggle_close(w);
}
w.write_str("}");
}
CtorKind::Fn => {
Expand Down
Loading