squiid/rust
1
0
Fork 0
Code Issues Pull requests Projects Activity

Rollup merge of #90089 - jsha:enum-fields-headings, r=camelid,GuillaumeGomez

Browse source 
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``
This commit is contained in:
Matthias Krüger 2021-11-20 01:09:38 +01:00 committed by GitHub
commit c0695bbf60
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 89 additions and 48 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
src/librustdoc/html/render/print_item.rs
View file

@ -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,
@ -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 {
@ -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(_)) => {}
@ -1126,7 +1120,8 @@ 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>",
@ -1134,13 +1129,16 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum
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);
}
}
let def_id = it.def_id.expect_def_id();

35
src/librustdoc/html/static/css/rustdoc.css
View file

@ -1102,25 +1102,28 @@ a.test-arrow:hover{
margin-right: 5px;
}
.sub-variant, .sub-variant > h3 {
margin-top: 0px !important;
padding-top: 1px;
}
#main .sub-variant > h3 {
font-size: 15px;
margin-left: 25px;
margin-bottom: 5px;
}
.sub-variant > div {
margin-left: 20px;
h3.variant {
font-weight: 600;
font-size: 1.1em;
margin-bottom: 10px;
border-bottom: none;
}
.sub-variant > div > span {
display: block;
position: relative;
.sub-variant h4 {
font-size: 1em;
font-weight: 400;
border-bottom: none;
margin-top: 0;
margin-bottom: 0;
}
.sub-variant {
margin-left: 24px;
margin-bottom: 40px;
}
.sub-variant > .sub-variant-field {
margin-left: 24px;
}
.toggle-label {

34
src/test/rustdoc-gui/headings.goml
View file

@ -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
@ -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: ("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: ("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#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: ("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: ("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: ("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: ("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"})

40
src/test/rustdoc/enum-headings.rs Normal file
View file

@ -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
src/test/rustdoc/tuple-struct-fields-doc.rs
View file

@ -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