Skip to content

Commit

Permalink
Auto merge of rust-lang#84754 - GuillaumeGomez:toggle-migration, r=jsha
Browse files Browse the repository at this point in the history 
Migrate trait and impl blocks' toggles into

Part of rust-lang#83332

After this, I think only the "global" doc comment will be used as JS toggle. Once this PR is merged, I check what remains and remove them.

There is one change that this PR brings:

![Screenshot from 2021-04-30 15-39-04](https://user-images.githubusercontent.com/3050060/116713412-0f9ce200-a9d5-11eb-979c-2e7a73d16706.png)
![Screenshot from 2021-04-30 15-39-07](https://user-images.githubusercontent.com/3050060/116713415-10357880-a9d5-11eb-9868-1ba9e5ebf65e.png)

As you can see, I had to move the "undocumented" items below, they're not mixed with the others anymore. Unfortunately, I don't see a way to keep the current appearance without JS. As a a reminder, currently it looks like this:

![Screenshot from 2021-04-30 15-39-12](https://user-images.githubusercontent.com/3050060/116713547-31966480-a9d5-11eb-90bb-686042eefeec.png)
![Screenshot from 2021-04-30 15-39-15](https://user-images.githubusercontent.com/3050060/116713549-322efb00-a9d5-11eb-94a9-cfea073120db.png)

r? `@jsha`
  • Loading branch information
@bors
bors committed May 2, 2021
2 parents e10cbc3 + 0d52eb9 commit 6b5de7a
Show file tree
Hide file tree
Showing 12 changed files with 186 additions and 232 deletions.
4 changes: 0 additions & 4 deletions src/librustdoc/clean/types.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -678,10 +678,6 @@ impl ItemKind {
| KeywordItem(_) => [].iter(),
}
}

crate fn is_type_alias(&self) -> bool {
matches!(self, ItemKind::TypedefItem(..) | ItemKind::AssocTypeItem(..))
}
}

#[derive(Clone, Debug)]
Expand Down
187 changes: 89 additions & 98 deletions src/librustdoc/html/render/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -508,23 +508,16 @@ fn document(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, parent: Option
if let Some(ref name) = item.name {
info!("Documenting {}", name);
}
document_item_info(w, cx, item, false, parent);
document_full(w, item, cx, false);
document_item_info(w, cx, item, parent);
document_full(w, item, cx);
}

/// Render md_text as markdown.
fn render_markdown(
w: &mut Buffer,
cx: &Context<'_>,
md_text: &str,
links: Vec<RenderedLink>,
is_hidden: bool,
) {
fn render_markdown(w: &mut Buffer, cx: &Context<'_>, md_text: &str, links: Vec<RenderedLink>) {
let mut ids = cx.id_map.borrow_mut();
write!(
w,
"<div class=\"docblock{}\">{}</div>",
if is_hidden { " hidden" } else { "" },
"<div class=\"docblock\">{}</div>",
Markdown(
md_text,
&links,
Expand All @@ -544,11 +537,10 @@ fn document_short(
item: &clean::Item,
cx: &Context<'_>,
link: AssocItemLink<'_>,
is_hidden: bool,
parent: &clean::Item,
show_def_docs: bool,
) {
document_item_info(w, cx, item, is_hidden, Some(parent));
document_item_info(w, cx, item, Some(parent));
if !show_def_docs {
return;
}
Expand All @@ -565,19 +557,14 @@ fn document_short(
}
}

write!(
w,
"<div class='docblock{}'>{}</div>",
if is_hidden { " hidden" } else { "" },
summary_html,
);
write!(w, "<div class='docblock'>{}</div>", summary_html,);
}
}

fn document_full(w: &mut Buffer, item: &clean::Item, cx: &Context<'_>, is_hidden: bool) {
fn document_full(w: &mut Buffer, item: &clean::Item, cx: &Context<'_>) {
if let Some(s) = cx.shared.maybe_collapsed_doc_value(item) {
debug!("Doc block: =====\n{}\n=====", s);
render_markdown(w, cx, &s, item.links(cx), is_hidden);
render_markdown(w, cx, &s, item.links(cx));
}
}

Expand All @@ -590,16 +577,11 @@ fn document_item_info(
w: &mut Buffer,
cx: &Context<'_>,
item: &clean::Item,
is_hidden: bool,
parent: Option<&clean::Item>,
) {
let item_infos = short_item_info(item, cx, parent);
if !item_infos.is_empty() {
if is_hidden {
w.write_str("<div class=\"item-info hidden\">");
} else {
w.write_str("<div class=\"item-info\">");
}
w.write_str("<div class=\"item-info\">");
for info in item_infos {
w.write_str(&info);
}
Expand Down Expand Up @@ -1282,8 +1264,12 @@ fn render_impl(
let trait_ = i.trait_did_full(cache).map(|did| &traits[&did]);
let mut close_tags = String::new();

// For trait implementations, the `interesting` output contains all methods that have doc
// comments, and the `boring` output contains all methods that do not. The distinction is
// used to allow hiding the boring methods.
fn doc_impl_item(
w: &mut Buffer,
boring: &mut Buffer,
interesting: &mut Buffer,
cx: &Context<'_>,
item: &clean::Item,
parent: &clean::Item,
Expand All @@ -1306,15 +1292,46 @@ fn render_impl(
}
};

let (is_hidden, extra_class) =
if (trait_.is_none() || item.doc_value().is_some() || item.kind.is_type_alias())
&& !is_default_item
{
(false, "")
} else {
(true, " hidden")
};
let in_trait_class = if trait_.is_some() { " trait-impl" } else { "" };

let mut doc_buffer = Buffer::empty_from(boring);
let mut info_buffer = Buffer::empty_from(boring);
let mut short_documented = true;

if render_method_item {
if !is_default_item {
if let Some(t) = trait_ {
// The trait item may have been stripped so we might not
// find any documentation or stability for it.
if let Some(it) = t.items.iter().find(|i| i.name == item.name) {
// We need the stability of the item from the trait
// because impls can't have a stability.
if item.doc_value().is_some() {
document_item_info(&mut info_buffer, cx, it, Some(parent));
document_full(&mut doc_buffer, item, cx);
short_documented = false;
} else {
// In case the item isn't documented,
// provide short documentation from the trait.
document_short(&mut doc_buffer, it, cx, link, parent, show_def_docs);
}
}
} else {
document_item_info(&mut info_buffer, cx, item, Some(parent));
if show_def_docs {
document_full(&mut doc_buffer, item, cx);
short_documented = false;
}
}
} else {
document_short(&mut doc_buffer, item, cx, link, parent, show_def_docs);
}
}
let w = if short_documented && trait_.is_some() { interesting } else { boring };

if !doc_buffer.is_empty() {
w.write_str("<details class=\"rustdoc-toggle\" open><summary>");
}
match *item.kind {
clean::MethodItem(..) | clean::TyMethodItem(_) => {
// Only render when the method is not static or we allow static methods
Expand All @@ -1327,11 +1344,7 @@ fn render_impl(
})
})
.map(|item| format!("{}.{}", item.type_(), name));
write!(
w,
"<h4 id=\"{}\" class=\"{}{}{}\">",
id, item_type, extra_class, in_trait_class,
);
write!(w, "<h4 id=\"{}\" class=\"{}{}\">", id, item_type, in_trait_class,);
w.write_str("<code>");
render_assoc_item(
w,
Expand All @@ -1356,11 +1369,7 @@ fn render_impl(
clean::TypedefItem(ref tydef, _) => {
let source_id = format!("{}.{}", ItemType::AssocType, name);
let id = cx.derive_id(source_id.clone());
write!(
w,
"<h4 id=\"{}\" class=\"{}{}{}\"><code>",
id, item_type, extra_class, in_trait_class
);
write!(w, "<h4 id=\"{}\" class=\"{}{}\"><code>", id, item_type, in_trait_class);
assoc_type(
w,
item,
Expand All @@ -1377,11 +1386,7 @@ fn render_impl(
clean::AssocConstItem(ref ty, ref default) => {
let source_id = format!("{}.{}", item_type, name);
let id = cx.derive_id(source_id.clone());
write!(
w,
"<h4 id=\"{}\" class=\"{}{}{}\"><code>",
id, item_type, extra_class, in_trait_class
);
write!(w, "<h4 id=\"{}\" class=\"{}{}\"><code>", id, item_type, in_trait_class);
assoc_const(
w,
item,
Expand All @@ -1406,11 +1411,7 @@ fn render_impl(
clean::AssocTypeItem(ref bounds, ref default) => {
let source_id = format!("{}.{}", item_type, name);
let id = cx.derive_id(source_id.clone());
write!(
w,
"<h4 id=\"{}\" class=\"{}{}{}\"><code>",
id, item_type, extra_class, in_trait_class
);
write!(w, "<h4 id=\"{}\" class=\"{}{}\"><code>", id, item_type, in_trait_class);
assoc_type(
w,
item,
Expand All @@ -1428,38 +1429,20 @@ fn render_impl(
_ => panic!("can't make docs for trait item with name {:?}", item.name),
}

if render_method_item {
if !is_default_item {
if let Some(t) = trait_ {
// The trait item may have been stripped so we might not
// find any documentation or stability for it.
if let Some(it) = t.items.iter().find(|i| i.name == item.name) {
// We need the stability of the item from the trait
// because impls can't have a stability.
if item.doc_value().is_some() {
document_item_info(w, cx, it, is_hidden, Some(parent));
document_full(w, item, cx, is_hidden);
} else {
// In case the item isn't documented,
// provide short documentation from the trait.
document_short(w, it, cx, link, is_hidden, parent, show_def_docs);
}
}
} else {
document_item_info(w, cx, item, is_hidden, Some(parent));
if show_def_docs {
document_full(w, item, cx, is_hidden);
}
}
} else {
document_short(w, item, cx, link, is_hidden, parent, show_def_docs);
}
w.push_buffer(info_buffer);
if !doc_buffer.is_empty() {
w.write_str("</summary>");
w.push_buffer(doc_buffer);
w.push_str("</details>");
}
}

let mut impl_items = Buffer::empty_from(w);
let mut default_impl_items = Buffer::empty_from(w);

for trait_item in &i.inner_impl().items {
doc_impl_item(
&mut default_impl_items,
&mut impl_items,
cx,
trait_item,
Expand All @@ -1475,7 +1458,8 @@ fn render_impl(
}

fn render_default_items(
w: &mut Buffer,
boring: &mut Buffer,
interesting: &mut Buffer,
cx: &Context<'_>,
t: &clean::Trait,
i: &clean::Impl,
Expand All @@ -1495,7 +1479,8 @@ fn render_impl(
let assoc_link = AssocItemLink::GotoSource(did, &provided_methods);

doc_impl_item(
w,
boring,
interesting,
cx,
trait_item,
parent,
Expand All @@ -1517,6 +1502,7 @@ fn render_impl(
if show_default_items {
if let Some(t) = trait_ {
render_default_items(
&mut default_impl_items,
&mut impl_items,
cx,
&t.trait_,
Expand All @@ -1529,10 +1515,14 @@ fn render_impl(
);
}
}
let details_str = if impl_items.is_empty() {
""
} else {
"<details class=\"rustdoc-toggle implementors-toggle\" open><summary>"
let toggled = !impl_items.is_empty() || !default_impl_items.is_empty();
let open_details = |close_tags: &mut String| {
if toggled {
close_tags.insert_str(0, "</details>");
"<details class=\"rustdoc-toggle implementors-toggle\" open><summary>"
} else {
""
}
};
if render_mode == RenderMode::Normal {
let id = cx.derive_id(match i.inner_impl().trait_ {
Expand All @@ -1554,11 +1544,10 @@ fn render_impl(
write!(
w,
"{}<h3 id=\"{}\" class=\"impl\"{}><code class=\"in-band\">",
details_str, id, aliases
open_details(&mut close_tags),
id,
aliases
);
if !impl_items.is_empty() {
close_tags.insert_str(0, "</details>");
}
write!(w, "{}", i.inner_impl().print(use_absolute, cx));
if show_def_docs {
for it in &i.inner_impl().items {
Expand All @@ -1582,14 +1571,11 @@ fn render_impl(
write!(
w,
"{}<h3 id=\"{}\" class=\"impl\"{}><code class=\"in-band\">{}</code>",
details_str,
open_details(&mut close_tags),
id,
aliases,
i.inner_impl().print(false, cx)
);
if !impl_items.is_empty() {
close_tags.insert_str(0, "</details>");
}
}
write!(w, "<a href=\"#{}\" class=\"anchor\"></a>", id);
render_stability_since_raw(
Expand All @@ -1600,7 +1586,7 @@ fn render_impl(
outer_const_version,
);
write_srclink(cx, &i.impl_item, w);
if impl_items.is_empty() {
if !toggled {
w.write_str("</h3>");
} else {
w.write_str("</h3></summary>");
Expand Down Expand Up @@ -1629,8 +1615,13 @@ fn render_impl(
);
}
}
if !impl_items.is_empty() {
if toggled {
w.write_str("<div class=\"impl-items\">");
w.push_buffer(default_impl_items);
if trait_.is_some() && !impl_items.is_empty() {
w.write_str("<details class=\"undocumented\"><summary></summary>");
close_tags.insert_str(0, "</details>");
}
w.push_buffer(impl_items);
close_tags.insert_str(0, "</div>");
}
Expand Down
Loading

0 comments on commit 6b5de7a

Please sign in to comment.