Improve display of enum variants #90089

jsha · 2021-10-20T05:54:08Z

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

rust-highfive · 2021-10-20T05:54:10Z

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez

Urgau · 2021-10-20T08:35:52Z

Just a quick message to say that I think that the layout is (with your changes) even more confusing. I don't know where I should put my eyes. The variant name is so big that it's disturbing, I feel that I should stop at every single of them. The all "Variant" layout feels out of place with the rest of the documentation.

Maybe instead of putting the variant name in h{3,4} you could make it bolder, this would would accentuate the difference but not be as disturbing as your changes.

jsha · 2021-10-20T15:22:37Z

Great feedback, thanks. I'm keeping the h3 / h4 (since that's a structural, not a display issue) but I adjusted the CSS to match your recommendation: now both h3 and h4 for variants are font-size: 16, but h3 is font-weight: 600. This is nicely consistent with how we render method headings.

Updated the demos.

camelid · 2021-10-20T16:11:46Z

Can you add a demo for what it looks like when some of the fields have documentation?

jsha · 2021-10-20T17:09:03Z

I updated the xmlparser / Token demo to include documentation on the fields:

https://jacob.hoffman-andrews.com/rust/xmlparser-updated/xmlparser/enum.Token.html#variants

camelid · 2021-10-20T17:14:51Z

One thing I'd suggest is to add a bit more space between the variant heading and "Fields" and between the fields and the variant's docs. Right now it looks a bit cramped to me.

jsha · 2021-10-20T17:20:42Z

Happy to do so! Would you mind trying out some spacing options in your developer tools and suggesting one that looks good to you? I'm happy to keep iterating on this but I suspect we'll save some round trips this way. :-)

Urgau · 2021-10-20T17:25:00Z

Nice, way better.

One thing, it think you can completely remove the "Fields" title (we can clearly tell that they are fields). This would look like this:

This would simplify the layout to only let the important information.

camelid · 2021-10-20T17:26:48Z

One thing, it think you can completely remove the "Fields" title (we can clearly tell that they are fields).

I was going to suggest this, but one problem is that for tuple fields, the docs might be confusing. The fields aren't actually named 0, 1, etc., but if you remove that heading, there's no indication that they belong to a tuple variant.

Urgau · 2021-10-20T17:28:50Z

The diff from my changes:

- .sub-variant > span {
-    margin-left: 20px;
- }

  .sub-variant {
     margin-left: 24px;
-    margin-bottom: 10px;
+    margin-bottom: 15px;
  }

plus the removal of the h4 "Fields".

GuillaumeGomez · 2021-10-21T09:11:54Z

One thing, it think you can completely remove the "Fields" title (we can clearly tell that they are fields).

I was going to suggest this, but one problem is that for tuple fields, the docs might be confusing. The fields aren't actually named 0, 1, etc., but if you remove that heading, there's no indication that they belong to a tuple variant.

Currently they are, so I don't see this as an issue.

@jsha: I find it harder to read the documentation because it's actually not that easy to find where the field starts and where its documentation starts.

jsha · 2021-10-21T16:40:56Z

I've updated the CSS like so:

More vertical separation between variant name and the "Fields" heading.
More vertical separation between the bottom of the variant's fields and the beginning of the variant's documentation.
Leftward indentation is bigger and more consistent with what we do elsewhere: 24px.

I think this should improve visual distinctiveness between the bottom of the fields and the beginning of the doccomment. I don't want to remove the "Fields" heading right now, since I think it is important for explaining the section it comes in front of.

Also I'd like to point out this is intended to be a quick fix for some significant problems with the display of enum field variants (horizontal line inverts the hierarchy; fields show up below doccomment; fields heading is bold, inverting the hierarchy). I always want to try and get the details right, of course, but I also don't want to let a few pixels of whitespace take up too much time here - there are other big display issues I'd like to move on to fixing, also.

camelid · 2021-10-21T20:44:35Z

I was going to suggest this, but one problem is that for tuple fields, the docs might be confusing. The fields aren't actually named 0, 1, etc., but if you remove that heading, there's no indication that they belong to a tuple variant.

Currently they are, so I don't see this as an issue.

What do you mean by "currently they are"? The issue I was describing is that in the docs, the fields are displayed as 0: etc., which makes it look like the variant was defined as Variant { 0: i32 }, which is invalid syntax. That's why it seems potentially useful to keep the "Tuple Fields" header, to make it clear that it's actually a tuple variant.

camelid · 2021-10-21T20:53:45Z

I've updated the CSS like so: [...]

Ah, this looks much better, thank you! After this change, the docs feel much less cramped to me. I only have two remaining comments about the UI (haven't looked at the impl yet):

Putting the fields before the variant's doc-comment seems like it could be confusing. The variant's docs are the summary, while the fields are the details; and in general, one would not put the summary after the details. Can you explain your rationale for this change? I feel that it might be best to leave it as-is for now and just make the heading, spacing, etc. improvements. That way we can make incremental progress without this PR getting stalled on other parts of the change.
I think the visual hierarchy would be a bit clearer if the font-size of the variant's name were increased from 1em to 1.1em. What do you think? It looks like this if I edit in devtools:

jsha · 2021-10-22T01:14:00Z

Putting the fields before the variant's doc-comment seems like it could be confusing. The variant's docs are the summary, while the fields are the details; and in general, one would not put the summary after the details. Can you explain your rationale for this change?

In other places, the doccomment is always the last part of a section, and fields / other generated stuff is at the top. Consider the top of the page, for instance - it has struct contents, or enum contents, and then the doccomment underneath. However, I don't feel strongly about this, so I've reverted to the previous behavior of fields on the bottom.

I've also updated the font sizes as you suggest, and pushed the demos.

GuillaumeGomez · 2021-10-22T19:11:05Z

I'm realizing now that the [+]/[-] symbols are actually great helper to identify item vs documentation... With just playing on the separation, it's not enough (at least not for me).

Can we have a symbol or symbol or something making it easier to spot the fields?

jsha · 2021-10-22T20:16:02Z

Can you tell me more about what you mean by "identify item vs documentation?" Are you saying that the "Fields" heading and the lines below it look like they are prose documentation written by the doc author? Or that you're scanning the docblock looking for the break between prose and Rusty items, and finding that the break doesn't catch the attention enough?

GuillaumeGomez · 2021-10-22T20:17:50Z

Or that you're scanning the docblock looking for the break between prose and Rusty items, and finding that the break doesn't catch the attention enough?

I meant that. It's hard to know if I'm still reading documentation or if it's a field. I have to stop and look a bit around to have this answer, which is not great.

camelid · 2021-10-22T20:48:15Z

I'm realizing now that the [+]/[-] symbols are actually great helper to identify item vs documentation... With just playing on the separation, it's not enough (at least not for me).

Can we have a symbol or symbol or something making it easier to spot the fields?

Would moving the fields docs to right below the variant's name like they were earlier in this PR make it easier for you? I agree that the fields look a bit like they're part of the docs themselves. I'd rather put the fields above the variant's docs than add more symbols to the docs though.

GuillaumeGomez · 2021-10-22T20:54:57Z

Worth a try!

jsha · 2021-10-22T21:08:57Z

Before I go back to that, I have one more idea to try:

This increases the font-weight on Fields to 500, and changes the color to blue. That matches the styling we use for Markdown prose headings elsewhere. Note: The blue indicates a hyperlink, so if we proceed with this I'll change Fields to be a hyperlink that points to its own anchor, the same as other prose headings.

If this is not satisfactory I'm perfectly happy going back to fields-on-top. Let me know which you prefer!

camelid · 2021-10-22T21:11:14Z

This increases the font-weight on Fields to 500, and changes the color to blue. That matches the styling we use for Markdown prose headings elsewhere. Note: The blue indicates a hyperlink, so if we proceed with this I'll change Fields to be a hyperlink that points to its own anchor, the same as other prose headings.

I think this adds more complexity and actually makes the docs more confusing. The issue is that "Fields" looks like it's part of the prose, and this makes it look even more like it's part of the prose. Also, I think we should be leaning away from adding more colors and links to the docs.

jsha · 2021-10-22T21:16:54Z

Good point, thanks. Back to fields-on-top. Demos updated - don't forget to hard-refresh.

camelid

This is a good improvement, thanks for doing this! I'll review the code soon; for now I have one last UI suggestion.

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

bors · 2021-10-30T23:11:05Z

☔ The latest upstream changes (presumably #90422) made this pull request unmergeable. Please resolve the merge conflicts.

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.

camelid · 2021-11-05T04:15:04Z

(I'll try to review this soon.)

camelid

The Rust changes mostly look fine to me, but I'd like @GuillaumeGomez to review the CSS/HTML tests.

camelid · 2021-11-17T17:48:21Z

src/librustdoc/html/render/print_item.rs

            }
+
+            document(w, cx, variant, Some(it), HeadingOffset::H4);


Hmm, should this be H3?

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

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

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.

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

GuillaumeGomez · 2021-11-17T19:21:59Z

Looks good to me as well. Once we have confirmation for @camelid's last message, we can approve it. :)

camelid · 2021-11-17T19:43:29Z

Once #90089 (comment) is addressed, r=camelid,GuillaumeGomez :)

jsha · 2021-11-19T07:13:01Z

@bors r=camelid,GuillaumeGomez rollup

bors · 2021-11-19T07:13:03Z

📌 Commit 69df43b has been approved by camelid,GuillaumeGomez

…d,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 rust-lang#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`

camelid · 2021-11-19T15:22:31Z

Thanks again for making this great UI improvement!

…d,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 rust-lang#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`

…askrgr Rollup of 8 pull requests Successful merges: - rust-lang#88361 (Makes docs for references a little less confusing) - rust-lang#90089 (Improve display of enum variants) - rust-lang#90956 (Add a regression test for rust-lang#87573) - rust-lang#90999 (fix CTFE/Miri simd_insert/extract on array-style repr(simd) types) - rust-lang#91026 (rustdoc doctest: detect `fn main` after an unexpected semicolon) - rust-lang#91035 (Put back removed empty line) - rust-lang#91044 (Turn all 0x1b_u8 into '\x1b' or b'\x1b') - rust-lang#91054 (rustdoc: Fix some unescaped HTML tags in docs) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup

rust-highfive assigned camelid Oct 20, 2021

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Oct 20, 2021

This comment has been minimized.

Sign in to view

jsha force-pushed the enum-fields-headings branch 2 times, most recently from 37d9c45 to 53d5ed8 Compare October 20, 2021 07:36

jsha added the A-rustdoc-ui Area: Rustdoc UI (generated HTML) label Oct 20, 2021

camelid reviewed Oct 23, 2021

View reviewed changes

src/librustdoc/html/static/css/rustdoc.css Outdated Show resolved Hide resolved

camelid added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Oct 30, 2021

jsha marked this pull request as ready for review October 30, 2021 04:57

Improve display of enum variants

69df43b

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.

jsha force-pushed the enum-fields-headings branch from 55725d5 to 69df43b Compare October 30, 2021 23:35

camelid reviewed Nov 17, 2021

View reviewed changes

GuillaumeGomez approved these changes Nov 17, 2021

View reviewed changes

camelid added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Nov 17, 2021

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Nov 19, 2021

matthiaskrgr mentioned this pull request Nov 19, 2021

Rollup of 5 pull requests #91041

Closed

matthiaskrgr mentioned this pull request Nov 19, 2021

Rollup of 9 pull requests #91048

Closed

matthiaskrgr mentioned this pull request Nov 20, 2021

Rollup of 8 pull requests #91064

Merged

bors merged commit c0695bb into rust-lang:master Nov 20, 2021

rustbot added this to the 1.58.0 milestone Nov 20, 2021

jyn514 mentioned this pull request Nov 24, 2021

rustdoc: Section icon color and font-weight has changed on nightly #91196

Closed

jsha deleted the enum-fields-headings branch January 25, 2022 04:32

GuillaumeGomez mentioned this pull request Mar 7, 2022

Rustdoc should link fields/variants to their corresponding section #74849

Closed

Improve display of enum variants #90089

Improve display of enum variants #90089

Conversation

jsha commented Oct 20, 2021

rust-highfive commented Oct 20, 2021

This comment has been minimized.

Urgau commented Oct 20, 2021

jsha commented Oct 20, 2021

camelid commented Oct 20, 2021

jsha commented Oct 20, 2021

camelid commented Oct 20, 2021

jsha commented Oct 20, 2021

Urgau commented Oct 20, 2021

camelid commented Oct 20, 2021 • edited Loading

Urgau commented Oct 20, 2021

GuillaumeGomez commented Oct 21, 2021

jsha commented Oct 21, 2021 • edited Loading

camelid commented Oct 21, 2021

camelid commented Oct 21, 2021

jsha commented Oct 22, 2021

GuillaumeGomez commented Oct 22, 2021

jsha commented Oct 22, 2021

GuillaumeGomez commented Oct 22, 2021

camelid commented Oct 22, 2021

GuillaumeGomez commented Oct 22, 2021

jsha commented Oct 22, 2021 • edited Loading

camelid commented Oct 22, 2021

jsha commented Oct 22, 2021 • edited Loading

camelid left a comment

Choose a reason for hiding this comment

bors commented Oct 30, 2021

camelid commented Nov 5, 2021

camelid left a comment

Choose a reason for hiding this comment

camelid Nov 17, 2021

Choose a reason for hiding this comment

GuillaumeGomez Nov 17, 2021

Choose a reason for hiding this comment

camelid Nov 17, 2021 • edited Loading

Choose a reason for hiding this comment

jsha Nov 19, 2021

Choose a reason for hiding this comment

camelid Nov 19, 2021

Choose a reason for hiding this comment

GuillaumeGomez commented Nov 17, 2021

camelid commented Nov 17, 2021

jsha commented Nov 19, 2021

bors commented Nov 19, 2021

camelid commented Nov 19, 2021

camelid commented Oct 20, 2021 •

edited

Loading

jsha commented Oct 21, 2021 •

edited

Loading

jsha commented Oct 22, 2021 •

edited

Loading

jsha commented Oct 22, 2021 •

edited

Loading

camelid Nov 17, 2021 •

edited

Loading