Add rustdoc documentation complexity toggle #16169
Conversation
| r##"<span id='render-detail'> | ||
| <button class='pill left inactive' id='render-simple'>simple</button><button | ||
| class='pill right active' id='render-detailed'>detailed</button> | ||
| </span>"##)); |
There was a problem hiding this comment.
To all reviewers: the buttons are line-broken in this weird way to avoid any whitespace between the two buttons, which would actually render.
|
FWIW, I couldn't tell which side of the pill button was activated and which side was not until clicking on it several times. (random idea: it could just be a |
| function renderDocsSimple(){ | ||
| $("#render-detailed").addClass("inactive").removeClass("active"); | ||
| $("#render-simple").addClass("active").removeClass("inactive"); | ||
| $(".docblock").hide(); |
There was a problem hiding this comment.
Couldn't this be done in CSS? i.e. add class to some parent element with a rule .summary-mode .docblock { display: none; } (this could also be used to control the styling of the buttons).
There was a problem hiding this comment.
The nice thing about my current design is you can individually hide/reveal the blocks by clicking on the function name. I don't think that works with your suggestion.
|
@huonw: I find your suggestion about a checkbox interesting. In fact, the more I think about it, you aren't even entering/exiting a state, you're just calling "collapse all" and "expand all". |
|
Refactored the thing to just have [collapse all] [expand all] "links" which is a much better UX in my mind. Also drastically reduces the amount of stuff this commit does. |
|
This is super interesting. I tweeted about it, let's see what some other people say. |
|
Said tweet is here: https://twitter.com/steveklabnik/status/495248942767288320 there's a couple of responses so far |
|
(expanding on my tweet response) |
|
If it's a toggle, we don't need to show both links at any time, right? Could we show only "Expand" when its collapsed and only "Collapse" when its expanded? |
|
@nham: it's no longer a toggle (well, it never really was, in practice). You should always be able to individually expand/collapse them individually. |
|
Made individual toggles explicit distinct entity. |
|
Those links are HUGE. Also, I was really hoping to get a subtle Is this kind of toggle really what we want anyway? I always figured we should have an expandable index of all functions at the top, to allow you to jump to a function. |
|
I suppose with everything collapsed the whole page kind of acts like an index. But it would be nice if the individual toggles could be much more subtle. They could also perhaps even go on the left side, in the margin between the stability indicator and the |
|
Yeah, the expansion links are probably going to have to go on the left, otherwise you get something like this, which is what it currently looks like on my machine: |
|
Yeah, the links are way too big. It should also really be a single link (at the top) that changes based on the state. Otherwise it brings too much noise to the mix. |
|
Moved link to the left, made subtler. Working on statefully toggling label between [+] and [-] |
|
Aaaand stateful. Alright, this looks a lot better now. Thanks for the feedback, everyone! |
|
That looks better. The margin changes when I toggle the button now though; it needs to have a fixed width. I'd also recommend making it a grey instead of a black. |
|
@kballard: the padding doesn't change, it's just that |
|
When one function has details and an adjacent one doesn't, the function signatures aren't aligned (but probably should be). Example:
|
|
@gankro The |
|
The toggle right now uses a |
|
@kballard I opted for position:absolute so that it has no influence over the positioning of its neighbours, solving both alignment issues. |
|
Better. Still 2 nitpicks:
The animation issues reproduce in both Safari and Chrome. |
|
Any animation issues are just a jQuery problem, as far as I know. I can just axe them, if you want (I'm just a sucker for sliding). I think what you're describing might be on purpose. E.G. they're trying to make it "bounce". I'll need to review their docs on slideUp/slideDown. Making +/- monospace seems like the right call. It just looks but-ugly if you make the |
|
Can you make the whole thing monospace, like the function signature, so we can see what it looks like? |
|
@kballard: done. I also tweaked the animation parameters to make it snappier. (changes uncommited) |
|
Snappier is good, but now I see what you mean about looking ugly. It's much wider than expected, and there's more space to the right of the |
|
What if you leave it in the original font, and just use a sub-span for the |
|
@kballard: that worked perfectly when combined with text-align:center :D |
|
Alright, I think that's all the issues addressed! |
|
Looks pretty good. I'm not entirely sold on having that I'm also not sure that indenting trait methods is correct when there's no At this point, I have no more concrete suggestions. I'll let someone else actually decide if this is appropriate though (I do not wish to claim any authority over how our documentation should look). Although I will say that you're going to have to squash your commits. |
|
Yeah indenting traits isn't perfect but I don't think it's worth entering elaborate case analysis for indentation-or-not behavior. Yep, I'll squash commits as soon as I get a peseudo-r on this. Who has any kind of authority on this matter? @cmr? @steveklabnik? |
|
I like it, but I'm not sure I have that authority. @huonw , what do you think? |
|
I'm happy with this, would r+ |
|
I was thinking that the toggle could be in the margin, like this: And then would show a short comment when collapsed: But right now it’s OK. Maybe that could be done in a separate PR. |
|
@cmr: Everything squashed |
|
@gankro can you implement @P1start's recommendation? |
|
The only complaint I have with this at the moment is that the toggles move into an awkward place when dealing with long struct names + smaller browser widths. I don't really know what the best way to handle small widths would be, however. Again, this could be saved for a later change . |
|
r=me if you do. |
|
As an aside: thank you so much, I love you ❤️ |
|
Alright, how's that look? @cmr @P1start |
|
It shows "Expand Description" too soon. During the collapse it's overlapping the text. Perhaps it can crossfade between the text and "Expand Description"? Also the width of the toggle on the description is too small. And there's a new bug where collapsing a function documentation doesn't update the toggle, until you expand and collapse again. Edit: I thought a second toggle fixed it, but now it appears that it's strictly the inverse of how it should (except it initializes to the correct value). |
|
Definitely in the kind of groggy state that produced the initial commit for this thing... Everything's gonna be down-hill from here, guys. Lets make some UX |
|
The ‘Expand Description’ message could have a tiny bit more padding underneath it, and changed to sentence case (i.e., ‘Expand description’, not ‘Expand Description’). Edit: Ideally the crossfade animation wouldn’t play when the ‘[collapse all]’ is pressed (because the slide animation doesn’t play either). |
|
Shout outs to the commit "muhh" which produces "[+] +" when you collapse. Quality level: ++ tier |
|
Alright, that last commit seems to not be awful, but working out the padding is gonna require a serious refactor, to be honest. The toggle needs to change how much space it occupies to do it properly. Gonna go to sleep, and poke at this when I'm not the worst at coding. |
|
Vastly more conscious now. How's it look now? |
|
When you hide the description toggle, the entire thing jumps down a line before the animation starts. |
|
Except for the issue @tinaun mentioned it looks good. |
All doccomments are now collapsable via a nearby [-] button Adds [collapse all] and [expand all] buttons to the top of all api pages Tweaks some layout to accomadate this
|
More transitiony now. Good? |
<strike>Adds a simple/detailed toggle to api doc pages. Detailed mode is the current behaviour, simple mode hides all doccomment details leaving only signatures for quick browsing. </strike> Adds [expand all] and [collapse all] "links" to all api doc pages. All doccomments are collapsed, leaving only signatures for quick browsing. In addition, clicking on a <strike>function name</strike> function's [toggle details] link now toggles the visibility of the associated doccomment. -------- # [Live Build Here](http://cg.scs.carleton.ca/~abeinges/doc/std/vec/struct.Vec.html) This is something that's been bothering me, and I've seen some people mention in IRC before. The docs are *great* if you want a full in-depth look at an API, but *awful* if you want to scan them. This provides the ability to toggle complexity freely. Interacts perfectly well with noscript, since the static page is effectively unchanged. Collapsing is just hiding divs with css. I'm not much of a designer, so design input welcome on the actual UX for toggling. The actual javascript is *a bit* brittle to layout changes, but it always will be without adding lots of extra junk to the actual markup, which didn't seem worth it.
|
Awesome. Thanks for all the feedback guys! Much better than anything I could have come up with alone. |
Adds a simple/detailed toggle to api doc pages.
Detailed mode is the current behaviour, simple mode hides all doccomment details leaving only signatures for quick browsing.
Adds [expand all] and [collapse all] "links" to all api doc pages. All doccomments are collapsed, leaving only signatures for quick browsing.
In addition, clicking on a
function namefunction's [toggle details] link now toggles the visibility of the associated doccomment.Live Build Here
This is something that's been bothering me, and I've seen some people mention in IRC before. The docs are great if you want a full in-depth look at an API, but awful if you want to scan them. This provides the ability to toggle complexity freely. Interacts perfectly well with noscript, since the static page is effectively unchanged. Collapsing is just hiding divs with css.
I'm not much of a designer, so design input welcome on the actual UX for toggling.
The actual javascript is a bit brittle to layout changes, but it always will be without adding lots of extra junk to the actual markup, which didn't seem worth it.