Migrate trait and impl blocks' toggles into #84754

GuillaumeGomez · 2021-04-30T14:57:57Z

After this, I think only the "global" doc comment will be used as JS toggle. Once this PR is merged, I check what remains and remove them.

There is one change that this PR brings:

As you can see, I had to move the "undocumented" items below, they're not mixed with the others anymore. Unfortunately, I don't see a way to keep the current appearance without JS. As a a reminder, currently it looks like this:

r? @jsha

rust-highfive · 2021-04-30T14:57: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

I think you need to add something around main.js line 1178, where we have showLargeItem / showImplementor, to make these toggles respond to their corresponding settings.

GuillaumeGomez · 2021-04-30T21:04:54Z

Completely forgot about the settings, you're absolutely right, great catch!

src/librustdoc/html/render/mod.rs

src/librustdoc/html/static/rustdoc.css

jsha · 2021-04-30T21:11:38Z

src/librustdoc/html/static/rustdoc.css

@@ -1810,3 +1833,14 @@ details.rustdoc-toggle[open] > summary::before {
 	content: "[−]";
 	display: inline;
 }
+
+details.undocumented > summary::before {
+	content: "[+] Show hidden undocumented items";


Interesting approach! This is different from how we've done the other toggles that have descriptions (hide-me), but it makes sense to do it this way, since this particular toggle has a description both in its open and in its closed state. 👍🏻

src/librustdoc/html/render/mod.rs

GuillaumeGomez · 2021-05-01T19:36:05Z

Fixed the settings application and applied your comments. Please tell me what you think of how I applied your closure idea.

jsha · 2021-05-01T22:48:55Z

src/librustdoc/html/static/main.js

+        if (hideMethodDocs === true) {
+            onEachLazy(document.getElementsByClassName("method"), function(e) {
+                var toggle = e.parentNode;
+                if (toggle) {
+                    toggle = toggle.parentNode;
                }
-            }
-        };
-
-        var funcImpl = function(e) {
-            var next = e.nextElementSibling;
-            if (next && hasClass(next, "item-info")) {
-                next = next.nextElementSibling;
-            }
-            if (next && hasClass(next, "docblock")) {
-                next = next.nextElementSibling;
-            }
-            if (!next) {
-                return;
-            }
-        };
+                if (toggle && toggle.tagName === "DETAILS") {
+                    toggle.open = false;
+                }
+            });
+        }


This would fit in more nicely as part of the onEachLazy(document.getElementsByTagName("details"), function (e) { loop below. That sections finds all the appropriate details tags and opens them if needed, which means we don't have to make the JS dependent on a very specific DOM structure by looking for a grandparent DETAILS node. Since methods are default-open, we would add a clause to say:

var hideMethod = hideMethods && hasClass(e, "methods-toggle"); if (hideMethod) { e.open = false; }

Note that we also need the class methods-toggle in the emitted HTML.

So I'm shared here: I'm not a big fan of the idea to grow the HTML, but that would indeed improve the JS. So after giving it some thought, here is what I suggest: we will move the "method"/"function"/etc classes from the h3/h4 into the grand-parent details. However, it seems to be out of context here, so if you're fine with it: I'll open an issue so that it can be done later and not be forgotten.

I agree HTML size is important, but I don't think we should economize by omitted classes when they are needed. That makes the CSS and JS more complex and harder to reason about. I'd rather look to bigger potential wins first - like deduplicating the tooltips subdocuments.

There's also an argument from consistency: We already put appropriate classes on the <details> tags we've added so far. It would be odd to economize on this one particular item type and not the others.

At any rate, I don't want to hold up the whole PR for the next week; I'm find landing this piece as-is and we can discuss more when I'm back.

src/librustdoc/html/static/rustdoc.css

src/librustdoc/html/render/mod.rs

jsha

r=me with the sense of the toggled variable inverted.

src/librustdoc/html/render/mod.rs

jsha · 2021-05-02T15:40:09Z

src/librustdoc/html/static/main.js

+        if (hideMethodDocs === true) {
+            onEachLazy(document.getElementsByClassName("method"), function(e) {
+                var toggle = e.parentNode;
+                if (toggle) {
+                    toggle = toggle.parentNode;
                }
-            }
-        };
-
-        var funcImpl = function(e) {
-            var next = e.nextElementSibling;
-            if (next && hasClass(next, "item-info")) {
-                next = next.nextElementSibling;
-            }
-            if (next && hasClass(next, "docblock")) {
-                next = next.nextElementSibling;
-            }
-            if (!next) {
-                return;
-            }
-        };
+                if (toggle && toggle.tagName === "DETAILS") {
+                    toggle.open = false;
+                }
+            });
+        }


I agree HTML size is important, but I don't think we should economize by omitted classes when they are needed. That makes the CSS and JS more complex and harder to reason about. I'd rather look to bigger potential wins first - like deduplicating the tooltips subdocuments.

There's also an argument from consistency: We already put appropriate classes on the <details> tags we've added so far. It would be odd to economize on this one particular item type and not the others.

At any rate, I don't want to hold up the whole PR for the next week; I'm find landing this piece as-is and we can discuss more when I'm back.

jsha · 2021-05-02T17:16:19Z

@bors r+

…

bors · 2021-05-02T17:16:20Z

📌 Commit 0d52eb9 has been approved by jsha

bors · 2021-05-02T19:46:14Z

⌛ Testing commit 0d52eb9 with merge 6b5de7a...

bors · 2021-05-02T21:56:19Z

☀️ Test successful - checks-actions
Approved by: jsha
Pushing 6b5de7a to master...

rust-highfive assigned jsha Apr 30, 2021

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

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

jsha requested changes Apr 30, 2021

View reviewed changes

jsha reviewed May 1, 2021

View reviewed changes

src/librustdoc/html/render/mod.rs Outdated Show resolved Hide resolved

GuillaumeGomez force-pushed the toggle-migration branch 2 times, most recently from a6cb17d to 65a3e25 Compare May 1, 2021 19:33

jsha requested changes May 1, 2021

View reviewed changes

GuillaumeGomez added 3 commits May 2, 2021 14:17

Migrate trait and impl blocks' toggles into

dfde867

Add missing CSS rules for associated types

5bd9146

Update tests

29777fc

GuillaumeGomez force-pushed the toggle-migration branch from 65a3e25 to 7b275da Compare May 2, 2021 12:20

jsha reviewed May 2, 2021

View reviewed changes

Improve code readability

0d52eb9

GuillaumeGomez force-pushed the toggle-migration branch from 7b275da to 0d52eb9 Compare May 2, 2021 17:12

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 2, 2021

GuillaumeGomez mentioned this pull request May 2, 2021

Move header CSS classes (such as "method"/"function"/etc) from h3/h4 into their parent #84829

Closed

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

bors merged commit 6b5de7a into rust-lang:master May 2, 2021

rustbot added this to the 1.54.0 milestone May 2, 2021

This was referenced May 2, 2021

rustdoc: Remove double toggle to show undocumented items #84317

Closed

Fix positioning for detail toggles on mobile. #84602

Closed

Clean up dom #84703

Merged

GuillaumeGomez deleted the toggle-migration branch May 3, 2021 08:27

This was referenced May 3, 2021

Clean up toggle logic in rustdoc #83332

Closed

rustdoc: remove redundant toggles for "undocumented items" #84326

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate trait and impl blocks' toggles into #84754

Migrate trait and impl blocks' toggles into #84754

GuillaumeGomez commented Apr 30, 2021

rust-highfive commented Apr 30, 2021

jsha left a comment

GuillaumeGomez commented Apr 30, 2021

jsha Apr 30, 2021

GuillaumeGomez commented May 1, 2021 •

edited

Loading

jsha May 1, 2021 •

edited

Loading

GuillaumeGomez May 2, 2021

jsha May 2, 2021

jsha left a comment •

edited

Loading

jsha May 2, 2021

jsha commented May 2, 2021 via email

bors commented May 2, 2021

bors commented May 2, 2021

bors commented May 2, 2021

Migrate trait and impl blocks' toggles into #84754

Migrate trait and impl blocks' toggles into #84754

Conversation

GuillaumeGomez commented Apr 30, 2021

rust-highfive commented Apr 30, 2021

jsha left a comment

Choose a reason for hiding this comment

GuillaumeGomez commented Apr 30, 2021

jsha Apr 30, 2021

Choose a reason for hiding this comment

GuillaumeGomez commented May 1, 2021 • edited Loading

jsha May 1, 2021 • edited Loading

Choose a reason for hiding this comment

GuillaumeGomez May 2, 2021

Choose a reason for hiding this comment

jsha May 2, 2021

Choose a reason for hiding this comment

jsha left a comment • edited Loading

Choose a reason for hiding this comment

jsha May 2, 2021

Choose a reason for hiding this comment

jsha commented May 2, 2021 via email

bors commented May 2, 2021

bors commented May 2, 2021

bors commented May 2, 2021

GuillaumeGomez commented May 1, 2021 •

edited

Loading

jsha May 1, 2021 •

edited

Loading

jsha left a comment •

edited

Loading