Migrate top doc and non-exhaustive toggles to details tag #85074

GuillaumeGomez · 2021-05-08T12:22:57Z

Fixes #83332.

r? @jsha

rust-highfive · 2021-05-08T12:22:59Z

Some changes occurred in HTML/CSS themes.

cc @GuillaumeGomez

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez

A change occurred in the Ayu theme.

cc @Cldfire

jsha · 2021-05-08T14:08:48Z

Yay! Thanks for getting this across the finish line. Writing from my phone so some brief things. Let's call the PR "migrate top doc and nom-exhaustive toggles to details tag." I think that would be most informative to someone reading through PRs later. I see you've used the CSS "content" property to show the text of the toggle. I know we've done this on one other toggle type but it makes me uneasy. For instance someone searching for where a text string comes from might look in the HTML or the JS, but not the CSS. I would prefer the approach I took in the decl-hiding change: put the text (e.g. expand non exhaustive) inside a `<summary class=hide-me>`. Also, I see a lot of repetitive CSS selectors. I think we can reduce those by giving our details tag the rustdoc-toggle class and selecting on that. In general all our toggles should have that class in addition to any others they have. Also I see you've removed the `non-exhaustive` class in preference for more specific classes. I'd like to keep it- I think it will make the CSS cleaner and more maintainable. I'm excited to see how much JS this lets us remove!

jsha · 2021-05-08T16:28:03Z

I see that document_full has a new boolean parameter, is_collapsible. I'm always wary of boolean params because it's not clear at the call site what they mean. How about this: at the one call site that has is_collapsible = true, emit the opening and closing details tags there rather than inside document_full? Also the CSS rules for the [+] that were formerly split can be merged since your latest updates.

GuillaumeGomez · 2021-05-08T18:02:00Z

I see that document_full has a new boolean parameter, is_collapsible. I'm always wary of boolean params because it's not clear at the call site what they mean. How about this: at the one call site that has is_collapsible = true, emit the opening and closing details tags there rather than inside document_full? Also the CSS rules for the [+] that were formerly split can be merged since your latest updates.

It's problematic in case there isn't any documentation generated because then we'd have a <details> with no content, which is why I went for this solution.

camelid · 2021-05-09T00:28:49Z

src/librustdoc/html/render/mod.rs

@@ -561,10 +561,21 @@ fn document_short(
    }
 }

-fn document_full(w: &mut Buffer, item: &clean::Item, cx: &Context<'_>) {
+fn document_full(w: &mut Buffer, item: &clean::Item, cx: &Context<'_>, is_collapsible: bool) {


nit: Could you use an enum instead? document_full(w, item, cx, true) doesn't tell me what the boolean means and could be confusing.

enum Collapsible { True, False } // Example usage document_full(w, item, cx, Collapsible::True);

Or, if you want to be able to use ifs, you could use a wrapper struct. This might be a better approach.

struct Collapsible { is: bool } // Example call document_full(w, item, cx, Collapsible { is: true }); // Example check if collapsible.is { /* ... */ }

I suggested naming the field is so that it's clear in the if conditional what the field is for.

Creating a new type for a boolean seems completely overkill. The argument name is pretty explicit in itself I think. Here what I will do: create another function called document_full_collapsible so that it doesn't require an extra argument and it will be explicit what it's doing. :)

The beauty of Rust's enums is that they're really easy to make and use. :-) But I'm good with document_full_collapsible if @camelid is.

Another possibility, going back to my idea of writing out the <details> wrapper at the call site: What if document_full returns an Option<Buffer>? Then the call sites can either splat the contents directly into their copy of w, or wrap them in <details> as appropriate.

I didn't want to create a new Buffer, but that could work too, just not as performant.

src/librustdoc/html/static/main.js

src/librustdoc/html/static/rustdoc.css

src/librustdoc/html/render/mod.rs

src/librustdoc/html/static/main.js

GuillaumeGomez · 2021-05-09T20:14:27Z

Applied review comments: a huge reduction of the JS size: more than 200 lines removed! \o/ That's one of the biggest reduction we've seen I think.

src/librustdoc/html/static/main.js

jsha · 2021-05-09T20:20:23Z

src/librustdoc/html/static/main.js

-                    hasClass(parent, "impl") === false) {
-                    e.innerHTML = labelForToggleButton(true);
+            onEachLazy(document.getElementsByClassName("rustdoc-toggle"), function(e) {
+                if (e.parentNode.id !== "main" ||


Why are direct children of main excluded from this?

Only the type declaration <details> and the impl blocks are ignored in this case (look in the or condition ;) ), like it's currently the case. I kept the same logic.

jsha · 2021-05-10T01:26:06Z

@bors r+

Nice work!

bors · 2021-05-10T01:26:08Z

📌 Commit 3837c1c has been approved by jsha

bors · 2021-05-10T04:05:59Z

⌛ Testing commit 3837c1c with merge 00f2bf4...

bors · 2021-05-10T06:30:03Z

☀️ Test successful - checks-actions
Approved by: jsha
Pushing 00f2bf4 to master...

…tester, r=Mark-Simulacrum Improve rustdoc gui tester I cherry-picked the commit from rust-lang#84834 (and modified it a bit). I also used this opportunity to update it to last version (forgot to update GUI test in rust-lang#85074, really can't wait to make rust-lang#84586 finally work). cc `@Mark-Simulacrum` for the changes in bootstrap. r? `@jsha`

…, r=GuillaumeGomez Move global click handlers to per-element ones. In rustdoc's main.js, we had an onclick handler for the whole document that would dispatch to handlers for various elements. This change attaches the handlers to the elements that trigger them, instead. This simplifies the code and avoids reimplementing the browser's bubbling functionality. As part of this change, change from a class to an id for help button. Move the handlers and associated code for highlighting source lines into source-script.js (and factor out a shared regex). Demo at https://hoffman-andrews.com/rust/bubble-bubble-toil-and-trouble/std/string/struct.String.html Note: this conflicts with / depends on rust-lang#85074. Once that's merged I'll rebase this and resolve conflicts. Part of rust-lang#83332. Thanks to `@Manishearth` for the [suggestion to not reimplement bubbling](rust-lang#83332 (comment)). r? `@GuillaumeGomez`

GuillaumeGomez added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-rustdoc-ui Area: rustdoc UI (generated HTML) A-rustdoc-js Area: Rustdoc's front-end labels May 8, 2021

rust-highfive assigned jsha May 8, 2021

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

This comment has been minimized.

Sign in to view

GuillaumeGomez changed the title ~~End toggle migration~~ Migrate top doc and nom-exhaustive toggles to details tag May 8, 2021

GuillaumeGomez force-pushed the end-toggle-migration branch from 913bfa4 to c42c1dd Compare May 8, 2021 15:52

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the end-toggle-migration branch from c42c1dd to fa8bfdc Compare May 8, 2021 18:22

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the end-toggle-migration branch from fa8bfdc to 35cf559 Compare May 8, 2021 20:44

GuillaumeGomez marked this pull request as ready for review May 8, 2021 20:44

camelid changed the title ~~Migrate top doc and nom-exhaustive toggles to details tag~~ Migrate top doc and non-exhaustive toggles to details tag May 9, 2021

camelid reviewed May 9, 2021

View reviewed changes

camelid added the C-cleanup Category: PRs that clean code up or issues documenting cleanup. label May 9, 2021

jsha requested changes May 9, 2021

View reviewed changes

GuillaumeGomez force-pushed the end-toggle-migration branch 2 times, most recently from 8eed102 to 987f5a6 Compare May 9, 2021 16:01

jsha reviewed May 9, 2021

View reviewed changes

src/librustdoc/html/static/main.js Outdated Show resolved Hide resolved

jsha mentioned this pull request May 9, 2021

Move global click handlers to per-element ones. #85117

Merged

GuillaumeGomez force-pushed the end-toggle-migration branch 2 times, most recently from 7fd40ba to b4dd386 Compare May 9, 2021 20:12

jsha reviewed May 9, 2021

View reviewed changes

src/librustdoc/html/static/main.js Outdated Show resolved Hide resolved

jsha reviewed May 9, 2021

View reviewed changes

GuillaumeGomez added 2 commits May 10, 2021 00:09

End toggle migration

4edcf61

Update rustdoc test

3837c1c

GuillaumeGomez force-pushed the end-toggle-migration branch from b4dd386 to 3837c1c Compare May 9, 2021 22:10

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-review Status: Awaiting review from the assignee but also interested parties. labels May 10, 2021

bors added the merged-by-bors This PR was explicitly merged by bors. label May 10, 2021

bors merged commit 00f2bf4 into rust-lang:master May 10, 2021

rustbot added this to the 1.54.0 milestone May 10, 2021

This was referenced May 10, 2021

rustdoc: Add unstable CLI option to show basic type layout information #83501

Merged

rustdoc: remove explicit boolean comparisons. #85124

Merged

GuillaumeGomez deleted the end-toggle-migration branch May 10, 2021 08:15

GuillaumeGomez mentioned this pull request May 11, 2021

Improve rustdoc gui tester #85191

Merged

Anders429 mentioned this pull request May 13, 2021

Support new doc HTML format Anders429/doc_item#14

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate top doc and non-exhaustive toggles to details tag #85074

Migrate top doc and non-exhaustive toggles to details tag #85074

GuillaumeGomez commented May 8, 2021

rust-highfive commented May 8, 2021

This comment has been minimized.

jsha commented May 8, 2021 via email

This comment has been minimized.

jsha commented May 8, 2021 via email

GuillaumeGomez commented May 8, 2021

This comment has been minimized.

camelid May 9, 2021

GuillaumeGomez May 9, 2021

jsha May 9, 2021

GuillaumeGomez May 9, 2021

GuillaumeGomez commented May 9, 2021

jsha May 9, 2021

GuillaumeGomez May 9, 2021

jsha commented May 10, 2021

bors commented May 10, 2021

bors commented May 10, 2021

bors commented May 10, 2021

Migrate top doc and non-exhaustive toggles to details tag #85074

Migrate top doc and non-exhaustive toggles to details tag #85074

Conversation

GuillaumeGomez commented May 8, 2021

rust-highfive commented May 8, 2021

This comment has been minimized.

jsha commented May 8, 2021 via email

This comment has been minimized.

jsha commented May 8, 2021 via email

GuillaumeGomez commented May 8, 2021

This comment has been minimized.

camelid May 9, 2021

Choose a reason for hiding this comment

GuillaumeGomez May 9, 2021

Choose a reason for hiding this comment

jsha May 9, 2021

Choose a reason for hiding this comment

GuillaumeGomez May 9, 2021

Choose a reason for hiding this comment

GuillaumeGomez commented May 9, 2021

jsha May 9, 2021

Choose a reason for hiding this comment

GuillaumeGomez May 9, 2021

Choose a reason for hiding this comment

jsha commented May 10, 2021

bors commented May 10, 2021

bors commented May 10, 2021

bors commented May 10, 2021