Skip to content

Improve display of enum variants #90089

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 1 commit into from
Nov 20, 2021
Merged

Improve display of enum variants #90089

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
24 changes: 11 additions & 13 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 @@ -1080,7 +1080,7 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum
cx.derive_id(format!("{}.{}", ItemType::Variant, variant.name.as_ref().unwrap()));
write!(
w,
"<div id=\"{id}\" class=\"variant small-section-header\">\
"<h3 id=\"{id}\" class=\"variant small-section-header\">\
<a href=\"#{id}\" class=\"anchor field\"></a>\
<code>{name}",
id = id,
Expand All @@ -1093,9 +1093,7 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum
}
w.write_str("</code>");
render_stability_since(w, variant, it, cx.tcx());
w.write_str("</div>");
document(w, cx, variant, Some(it), HeadingOffset::H3);
document_non_exhaustive(w, variant);
w.write_str("</h3>");

use crate::clean::Variant;
if let Some((extra, fields)) = match *variant.kind {
Expand All @@ -1109,12 +1107,8 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum
variant.name.as_ref().unwrap()
));
write!(w, "<div class=\"sub-variant\" id=\"{id}\">", id = variant_id);
write!(
w,
"<h3>{extra}Fields of <b>{name}</b></h3><div>",
extra = extra,
name = variant.name.as_ref().unwrap(),
);
write!(w, "<h4>{extra}Fields</h4>", extra = extra,);
document_non_exhaustive(w, variant);
for field in fields {
match *field.kind {
clean::StrippedItem(box clean::StructFieldItem(_)) => {}
Expand All @@ -1126,21 +1120,25 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum
));
write!(
w,
"<span id=\"{id}\" class=\"variant small-section-header\">\
"<div class=\"sub-variant-field\">\
<span id=\"{id}\" class=\"variant small-section-header\">\
<a href=\"#{id}\" class=\"anchor field\"></a>\
<code>{f}:&nbsp;{t}</code>\
</span>",
id = id,
f = field.name.as_ref().unwrap(),
t = ty.print(cx)
);
document(w, cx, field, Some(variant), HeadingOffset::H4);
document(w, cx, field, Some(variant), HeadingOffset::H5);
write!(w, "</div>");
}
_ => unreachable!(),
}
}
w.write_str("</div></div>");
w.write_str("</div>");
}

document(w, cx, variant, Some(it), HeadingOffset::H4);
Copy link
Member

Choose a reason for hiding this comment

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

Hmm, should this be H3?

Copy link
Member

Choose a reason for hiding this comment

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

I think (iirc) that it means the biggest heading will be h4 (please someone correct me if I'm wrong).

Copy link
Member

@camelid camelid Nov 17, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

But I think the heading immediately above (in the HTML, not the Rust source) is h3?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yes, this is correct. In the demo: https://rustdoc.crud.net/jsha/enum-headings/foo/enum.Token.html#variant.Declaration

"Declaration" is h3, and then "Variant-First" is h4, as it should be.

Copy link
Member

Choose a reason for hiding this comment

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

Ok, I guess I'm still confused by HeadingOffset's numbering.

}
}
let def_id = it.def_id.expect_def_id();
Expand Down
29 changes: 16 additions & 13 deletions src/librustdoc/html/static/css/rustdoc.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1101,25 +1101,28 @@ a.test-arrow:hover{
margin-right: 5px;
}

.sub-variant, .sub-variant > h3 {
margin-top: 0px !important;
padding-top: 1px;
h3.variant {
font-weight: 600;
font-size: 1.1em;
margin-bottom: 10px;
border-bottom: none;
}

#main .sub-variant > h3 {
font-size: 15px;
margin-left: 25px;
margin-bottom: 5px;
.sub-variant h4 {
font-size: 1em;
font-weight: 400;
border-bottom: none;
margin-top: 0;
margin-bottom: 0;
}

.sub-variant > div {
margin-left: 20px;
margin-bottom: 10px;
.sub-variant {
margin-left: 24px;
margin-bottom: 40px;
}

.sub-variant > div > span {
display: block;
position: relative;
.sub-variant > .sub-variant-field {
margin-left: 24px;
}

.toggle-label {
Expand Down
40 changes: 20 additions & 20 deletions src/test/rustdoc-gui/headings.goml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// This test check that headers (a) have the correct heading level, (b) are the right size,
// This test checks that headers (a) have the correct heading level, (b) are the right size,
// and (c) have the correct underlining (or absence of underlining).
// The sizes may change as design changes, but try to make sure a lower header is never bigger than
// its parent headers. Also make sure lower headers don't have underlines when their parents lack
Expand Down Expand Up @@ -67,25 +67,25 @@ assert-css: ("h4#top-doc-prose-sub-sub-heading", {"border-bottom-width": "1px"})
assert-css: ("h2#variants", {"font-size": "22.4px"})
assert-css: ("h2#variants", {"border-bottom-width": "1px"})

assert-css: ("h3#none-prose-title", {"font-size": "20.8px"})
assert-css: ("h3#none-prose-title", {"border-bottom-width": "0px"})
assert-css: ("h4#none-prose-sub-heading", {"font-size": "16px"})
assert-css: ("h4#none-prose-sub-heading", {"border-bottom-width": "0px"})

assert-css: ("h3#wrapped-prose-title", {"font-size": "20.8px"})
assert-css: ("h3#wrapped-prose-title", {"border-bottom-width": "0px"})
assert-css: ("h4#wrapped-prose-sub-heading", {"font-size": "16px"})
assert-css: ("h4#wrapped-prose-sub-heading", {"border-bottom-width": "0px"})

assert-css: ("h4#wrapped0-prose-title", {"font-size": "16px"})
assert-css: ("h4#wrapped0-prose-title", {"border-bottom-width": "0px"})
assert-css: ("h5#wrapped0-prose-sub-heading", {"font-size": "16px"})
assert-css: ("h5#wrapped0-prose-sub-heading", {"border-bottom-width": "0px"})

assert-css: ("h4#structy-prose-title", {"font-size": "16px"})
assert-css: ("h4#structy-prose-title", {"border-bottom-width": "0px"})
assert-css: ("h5#structy-prose-sub-heading", {"font-size": "16px"})
assert-css: ("h5#structy-prose-sub-heading", {"border-bottom-width": "0px"})
assert-css: ("h4#none-prose-title", {"font-size": "16px"})
assert-css: ("h4#none-prose-title", {"border-bottom-width": "0px"})
assert-css: ("h5#none-prose-sub-heading", {"font-size": "16px"})
assert-css: ("h5#none-prose-sub-heading", {"border-bottom-width": "0px"})

assert-css: ("h4#wrapped-prose-title", {"font-size": "16px"})
assert-css: ("h4#wrapped-prose-title", {"border-bottom-width": "0px"})
assert-css: ("h5#wrapped-prose-sub-heading", {"font-size": "16px"})
assert-css: ("h5#wrapped-prose-sub-heading", {"border-bottom-width": "0px"})

assert-css: ("h5#wrapped0-prose-title", {"font-size": "16px"})
assert-css: ("h5#wrapped0-prose-title", {"border-bottom-width": "0px"})
assert-css: ("h6#wrapped0-prose-sub-heading", {"font-size": "15.2px"})
assert-css: ("h6#wrapped0-prose-sub-heading", {"border-bottom-width": "0px"})

assert-css: ("h5#structy-prose-title", {"font-size": "16px"})
assert-css: ("h5#structy-prose-title", {"border-bottom-width": "0px"})
assert-css: ("h6#structy-prose-sub-heading", {"font-size": "15.2px"})
assert-css: ("h6#structy-prose-sub-heading", {"border-bottom-width": "0px"})

assert-css: ("h2#implementations", {"font-size": "22.4px"})
assert-css: ("h2#implementations", {"border-bottom-width": "1px"})
Expand Down
40 changes: 40 additions & 0 deletions src/test/rustdoc/enum-headings.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
#![crate_name = "foo"]
// @has foo/enum.Token.html
/// A token!
/// # First
/// Some following text...
// @has - '//h2[@id="first"]' "First"
pub enum Token {
/// A declaration!
/// # Variant-First
/// Some following text...
// @has - '//h4[@id="variant-first"]' "Variant-First"
Declaration {
/// A version!
/// # Variant-Field-First
/// Some following text...
// @has - '//h5[@id="variant-field-first"]' "Variant-Field-First"
version: String,
},
/// A Zoople!
/// # Variant-First
Zoople(
// @has - '//h5[@id="variant-tuple-field-first"]' "Variant-Tuple-Field-First"
/// Zoople's first variant!
/// # Variant-Tuple-Field-First
/// Some following text...
usize,
),
/// Unfinished business!
/// # Non-Exhaustive-First
/// Some following text...
// @has - '//h4[@id="non-exhaustive-first"]' "Non-Exhaustive-First"
#[non_exhaustive]
Unfinished {
/// This is x.
/// # X-First
/// Some following text...
// @has - '//h5[@id="x-first"]' "X-First"
x: usize,
},
}
4 changes: 2 additions & 2 deletions src/test/rustdoc/tuple-struct-fields-doc.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,10 @@ pub struct Foo(

// @has foo/enum.Bar.html
// @has - '//pre[@class="rust enum"]' 'BarVariant(String),'
// @matches - '//*[@id="variant.BarVariant.fields"]/h3' '^Tuple Fields of BarVariant$'
// @matches - '//*[@id="variant.BarVariant.fields"]/h4' '^Tuple Fields$'
// @has - '//*[@id="variant.BarVariant.field.0"]' '0: String'
// @has - '//*[@id="variant.BarVariant.fields"]//*[@class="docblock"]' 'Hello docs'
// @matches - '//*[@id="variant.FooVariant.fields"]/h3' '^Fields of FooVariant$'
// @matches - '//*[@id="variant.FooVariant.fields"]/h4' '^Fields$'
pub enum Bar {
BarVariant(
/// Hello docs
Expand Down