Skip to content

Commit c0695bb

Browse files
matthiaskrgrmatthiaskrgr
authored
Rollup merge of #90089 - jsha:enum-fields-headings, r=camelid,GuillaumeGomez
Improve display of enum variants Use h3 and h4 for the variant name and the "Fields" subheading. Remove the "of T" part of the "Fields" subheading. Remove border-bottom from "Fields" subheading. Move docblock below "Fields" listing. Fixes #90061 Demo: https://jacob.hoffman-andrews.com/rust/xmlparser-updated/xmlparser/enum.Token.html#variants https://jacob.hoffman-andrews.com/rust/fix-enum-variants/std/io/enum.ErrorKind.html#variants https://jacob.hoffman-andrews.com/rust/fix-enum-variants/std/result/enum.Result.html#variants r? ``@camelid``
2 parents 97bd45b + 69df43b commit c0695bb

File tree

5 files changed

+89
-48
lines changed

5 files changed

+89
-48
lines changed

‎src/librustdoc/html/render/print_item.rs

+11-13
Original file line numberDiff line numberDiff line change
@@ -1080,7 +1080,7 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum
10801080
cx.derive_id(format!("{}.{}", ItemType::Variant, variant.name.as_ref().unwrap()));
10811081
write!(
10821082
w,
1083-
"<div id=\"{id}\" class=\"variant small-section-header\">\
1083+
"<h3 id=\"{id}\" class=\"variant small-section-header\">\
10841084
<a href=\"#{id}\" class=\"anchor field\"></a>\
10851085
<code>{name}",
10861086
id = id,
@@ -1093,9 +1093,7 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum
10931093
}
10941094
w.write_str("</code>");
10951095
render_stability_since(w, variant, it, cx.tcx());
1096-
w.write_str("</div>");
1097-
document(w, cx, variant, Some(it), HeadingOffset::H3);
1098-
document_non_exhaustive(w, variant);
1096+
w.write_str("</h3>");
10991097

11001098
use crate::clean::Variant;
11011099
if let Some((extra, fields)) = match *variant.kind {
@@ -1109,12 +1107,8 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum
11091107
variant.name.as_ref().unwrap()
11101108
));
11111109
write!(w, "<div class=\"sub-variant\" id=\"{id}\">", id = variant_id);
1112-
write!(
1113-
w,
1114-
"<h3>{extra}Fields of <b>{name}</b></h3><div>",
1115-
extra = extra,
1116-
name = variant.name.as_ref().unwrap(),
1117-
);
1110+
write!(w, "<h4>{extra}Fields</h4>", extra = extra,);
1111+
document_non_exhaustive(w, variant);
11181112
for field in fields {
11191113
match *field.kind {
11201114
clean::StrippedItem(box clean::StructFieldItem(_)) => {}
@@ -1126,21 +1120,25 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum
11261120
));
11271121
write!(
11281122
w,
1129-
"<span id=\"{id}\" class=\"variant small-section-header\">\
1123+
"<div class=\"sub-variant-field\">\
1124+
<span id=\"{id}\" class=\"variant small-section-header\">\
11301125
<a href=\"#{id}\" class=\"anchor field\"></a>\
11311126
<code>{f}:&nbsp;{t}</code>\
11321127
</span>",
11331128
id = id,
11341129
f = field.name.as_ref().unwrap(),
11351130
t = ty.print(cx)
11361131
);
1137-
document(w, cx, field, Some(variant), HeadingOffset::H4);
1132+
document(w, cx, field, Some(variant), HeadingOffset::H5);
1133+
write!(w, "</div>");
11381134
}
11391135
_ => unreachable!(),
11401136
}
11411137
}
1142-
w.write_str("</div></div>");
1138+
w.write_str("</div>");
11431139
}
1140+
1141+
document(w, cx, variant, Some(it), HeadingOffset::H4);
11441142
}
11451143
}
11461144
let def_id = it.def_id.expect_def_id();

‎src/librustdoc/html/static/css/rustdoc.css

+16-13
Original file line numberDiff line numberDiff line change
@@ -1102,25 +1102,28 @@ a.test-arrow:hover{
11021102
margin-right: 5px;
11031103
}
11041104

1105-
.sub-variant, .sub-variant > h3 {
1106-
margin-top: 0px !important;
1107-
padding-top: 1px;
1105+
h3.variant {
1106+
font-weight: 600;
1107+
font-size: 1.1em;
1108+
margin-bottom: 10px;
1109+
border-bottom: none;
11081110
}
11091111

1110-
#main .sub-variant > h3 {
1111-
font-size: 15px;
1112-
margin-left: 25px;
1113-
margin-bottom: 5px;
1112+
.sub-variant h4 {
1113+
font-size: 1em;
1114+
font-weight: 400;
1115+
border-bottom: none;
1116+
margin-top: 0;
1117+
margin-bottom: 0;
11141118
}
11151119

1116-
.sub-variant > div {
1117-
margin-left: 20px;
1118-
margin-bottom: 10px;
1120+
.sub-variant {
1121+
margin-left: 24px;
1122+
margin-bottom: 40px;
11191123
}
11201124

1121-
.sub-variant > div > span {
1122-
display: block;
1123-
position: relative;
1125+
.sub-variant > .sub-variant-field {
1126+
margin-left: 24px;
11241127
}
11251128

11261129
.toggle-label {

‎src/test/rustdoc-gui/headings.goml

+20-20
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// This test check that headers (a) have the correct heading level, (b) are the right size,
1+
// This test checks that headers (a) have the correct heading level, (b) are the right size,
22
// and (c) have the correct underlining (or absence of underlining).
33
// The sizes may change as design changes, but try to make sure a lower header is never bigger than
44
// its parent headers. Also make sure lower headers don't have underlines when their parents lack
@@ -67,25 +67,25 @@ assert-css: ("h4#top-doc-prose-sub-sub-heading", {"border-bottom-width": "1px"})
6767
assert-css: ("h2#variants", {"font-size": "22.4px"})
6868
assert-css: ("h2#variants", {"border-bottom-width": "1px"})
6969

70-
assert-css: ("h3#none-prose-title", {"font-size": "20.8px"})
71-
assert-css: ("h3#none-prose-title", {"border-bottom-width": "0px"})
72-
assert-css: ("h4#none-prose-sub-heading", {"font-size": "16px"})
73-
assert-css: ("h4#none-prose-sub-heading", {"border-bottom-width": "0px"})
74-
75-
assert-css: ("h3#wrapped-prose-title", {"font-size": "20.8px"})
76-
assert-css: ("h3#wrapped-prose-title", {"border-bottom-width": "0px"})
77-
assert-css: ("h4#wrapped-prose-sub-heading", {"font-size": "16px"})
78-
assert-css: ("h4#wrapped-prose-sub-heading", {"border-bottom-width": "0px"})
79-
80-
assert-css: ("h4#wrapped0-prose-title", {"font-size": "16px"})
81-
assert-css: ("h4#wrapped0-prose-title", {"border-bottom-width": "0px"})
82-
assert-css: ("h5#wrapped0-prose-sub-heading", {"font-size": "16px"})
83-
assert-css: ("h5#wrapped0-prose-sub-heading", {"border-bottom-width": "0px"})
84-
85-
assert-css: ("h4#structy-prose-title", {"font-size": "16px"})
86-
assert-css: ("h4#structy-prose-title", {"border-bottom-width": "0px"})
87-
assert-css: ("h5#structy-prose-sub-heading", {"font-size": "16px"})
88-
assert-css: ("h5#structy-prose-sub-heading", {"border-bottom-width": "0px"})
70+
assert-css: ("h4#none-prose-title", {"font-size": "16px"})
71+
assert-css: ("h4#none-prose-title", {"border-bottom-width": "0px"})
72+
assert-css: ("h5#none-prose-sub-heading", {"font-size": "16px"})
73+
assert-css: ("h5#none-prose-sub-heading", {"border-bottom-width": "0px"})
74+
75+
assert-css: ("h4#wrapped-prose-title", {"font-size": "16px"})
76+
assert-css: ("h4#wrapped-prose-title", {"border-bottom-width": "0px"})
77+
assert-css: ("h5#wrapped-prose-sub-heading", {"font-size": "16px"})
78+
assert-css: ("h5#wrapped-prose-sub-heading", {"border-bottom-width": "0px"})
79+
80+
assert-css: ("h5#wrapped0-prose-title", {"font-size": "16px"})
81+
assert-css: ("h5#wrapped0-prose-title", {"border-bottom-width": "0px"})
82+
assert-css: ("h6#wrapped0-prose-sub-heading", {"font-size": "15.2px"})
83+
assert-css: ("h6#wrapped0-prose-sub-heading", {"border-bottom-width": "0px"})
84+
85+
assert-css: ("h5#structy-prose-title", {"font-size": "16px"})
86+
assert-css: ("h5#structy-prose-title", {"border-bottom-width": "0px"})
87+
assert-css: ("h6#structy-prose-sub-heading", {"font-size": "15.2px"})
88+
assert-css: ("h6#structy-prose-sub-heading", {"border-bottom-width": "0px"})
8989

9090
assert-css: ("h2#implementations", {"font-size": "22.4px"})
9191
assert-css: ("h2#implementations", {"border-bottom-width": "1px"})

‎src/test/rustdoc/enum-headings.rs

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
#![crate_name = "foo"]
2+
// @has foo/enum.Token.html
3+
/// A token!
4+
/// # First
5+
/// Some following text...
6+
// @has - '//h2[@id="first"]' "First"
7+
pub enum Token {
8+
/// A declaration!
9+
/// # Variant-First
10+
/// Some following text...
11+
// @has - '//h4[@id="variant-first"]' "Variant-First"
12+
Declaration {
13+
/// A version!
14+
/// # Variant-Field-First
15+
/// Some following text...
16+
// @has - '//h5[@id="variant-field-first"]' "Variant-Field-First"
17+
version: String,
18+
},
19+
/// A Zoople!
20+
/// # Variant-First
21+
Zoople(
22+
// @has - '//h5[@id="variant-tuple-field-first"]' "Variant-Tuple-Field-First"
23+
/// Zoople's first variant!
24+
/// # Variant-Tuple-Field-First
25+
/// Some following text...
26+
usize,
27+
),
28+
/// Unfinished business!
29+
/// # Non-Exhaustive-First
30+
/// Some following text...
31+
// @has - '//h4[@id="non-exhaustive-first"]' "Non-Exhaustive-First"
32+
#[non_exhaustive]
33+
Unfinished {
34+
/// This is x.
35+
/// # X-First
36+
/// Some following text...
37+
// @has - '//h5[@id="x-first"]' "X-First"
38+
x: usize,
39+
},
40+
}

‎src/test/rustdoc/tuple-struct-fields-doc.rs

+2-2
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,10 @@ pub struct Foo(
2020

2121
// @has foo/enum.Bar.html
2222
// @has - '//pre[@class="rust enum"]' 'BarVariant(String),'
23-
// @matches - '//*[@id="variant.BarVariant.fields"]/h3' '^Tuple Fields of BarVariant$'
23+
// @matches - '//*[@id="variant.BarVariant.fields"]/h4' '^Tuple Fields$'
2424
// @has - '//*[@id="variant.BarVariant.field.0"]' '0: String'
2525
// @has - '//*[@id="variant.BarVariant.fields"]//*[@class="docblock"]' 'Hello docs'
26-
// @matches - '//*[@id="variant.FooVariant.fields"]/h3' '^Fields of FooVariant$'
26+
// @matches - '//*[@id="variant.FooVariant.fields"]/h4' '^Fields$'
2727
pub enum Bar {
2828
BarVariant(
2929
/// Hello docs

0 commit comments

Comments
 (0)