-
Notifications
You must be signed in to change notification settings - Fork 12.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
rustdoc: design change to separate methods better and improve scanning #86283
Conversation
This reduces clutter on the page, while still supporting the "auto hide X" settings and the "collapse all docs" button.
This was originally introduced in # 51387, to solve a UI problem: in a list of collapsed methods, it was not clear whether the stability marker attached to the item above it or the one below it. That problem has now been solved in a couple of different ways: - The margin between the stability marker and the item it annotates is much smaller, indicating their relationship. - Stability markers are now collapsed along with the docblock. Also, the arrow made our CSS fragile, since it was positioned absolutely and needed to line up horizontally with the beginning of the item (or with the link icon). Aligning this with the rest of the docblock makes getting the CSS right a lot easier.
When methods are toggled open, add a border-top, some background highlighting, and tweak the spacing. Also remove the `pub fn` in front of the method name.
Some changes occurred in HTML/CSS/JS. Some changes occurred in HTML/CSS themes. A change occurred in the Ayu theme. cc @Cldfire |
r? @CraftSpider (rust-highfive has picked a reviewer for you, use r? to override) |
This comment has been minimized.
This comment has been minimized.
Oh this is an interesting take! I like it!
I think this is a good change, but we should do it consistently for all items, not just functions. |
I also think we should do the |
My idea for visibility was to show |
An interesting question. The same issue applies for other keywords that appear before the |
I think that makes sense, yes. I kind of want to hold off on deciding to remove |
The border looks really nice and definitely improves scanning, and I like the idea of removing |
Oh, @camelid you requested to be pinged if we were considering removing pub. |
☔ The latest upstream changes (presumably #86399) made this pull request unmergeable. Please resolve the merge conflicts. |
Sorry it's taken me a while to look at this. I love this! In fact I read the first few paragraphs and was like "hell yeah this is why I like the ReadTheDocs theme" and then you went on to say you were inspired by just that 😄 . A slight feeling is that the highlight shouldn't go away when collapsed, especially since it's a clickable region. I'm not so sure about removing the And there are lots of users of |
I think we should decouple the styling/collapsing change from removing pub/fn -- do the style change first, it stands pretty well on its own |
My thinking here is that, in a big list where every line is a method, the extra emphasis and separation of having a border and background color becomes noisy and actually hinders scanning. But I don't feel strongly about this - there's also a good argument for consistency between open and closed states.
Yep, fine with this.
To be clear: are you saying it's less of a learning curve to learn how to read the docs, or that docs looking like syntax helps with the learning curve of Rust's syntax (because people are repeatedly exposed to the syntax)? I look at it this way: Every element we put in the summary competes with every other element for a reader's attention. So, for instance, My somewhat more radical vision that I haven't fully formed is: the other modifiers ( |
When documenting private items, it's quite important to have the distinction somehow. Either by having "pub" or something else though (exactly as you said, just wanted to underline it a bit ;) ). |
So yes, overall I really like it. A small thought I had: for the This looks really promising! |
I like the new border styling a lot; it's helpful to have more visual separation. I wonder if
I feel similarly: In terms of
I wonder if a different approach could be to put things like I'm also wondering whether it might be useful to land part of this change behind a CLI flag, and then enable that flag by default for the nightly rustc API docs so we can get some user feedback before we fully land the change? |
Yeah the lack of consistency is jarring for me.
Mostly that the familiarity is nice, more of the former.
Oh I totally agree! However my counterargument here is that the order in which stuff appears in the source is familiar, people are already used to scanning that, this introduces a similar-but-not-identical syntax, which is going to be confusing. Perhaps we should instead use styling for emphasis and deemphasis? Perhaps grey out |
Give same highlighting to closed blocks. Smaller font size and weight for fn qualifiers, and same for `where` clauses. Use a darker highlight for the part of the bar directly over the function name.
I've made some tweaks and pushed a new candidate design. The demo is at a new URL, so you can compare with the old one: I restored One of the reasons I wanted to ditch
This is a neat idea. I tried it, but ran into a problem: We can make the
Impls should have some stronger visual distinction than they currently do, but not the same exact thing as the methods have. Perhaps making their font bigger / heavier?
Yep, I am very much onboard with making sure the experience of --document-private-items is good. I actually think adding text or another indicator that affirmatively marks something as private would be a better experience than the status quo. In the browser security world, there has been some research that shows people notice negative indicators but not the absence of normally positive indicators. That is, they notice "Not Secure", but they don't notice the absence of a "Secure" marking on a page that normally has it. I would guess it's somewhat hard to notice that
Ah, this is a good way to put it. So we have two values: familiarity vs ordering information by priority, and we are deciding how to trade off between them. The latest demo tries to make that tradeoff by using signposts (border colors, font sizes) to overlay a priority order on top of the left-to-right reading order. It works-ish, but I think it's still not ideal. It feels like improving clarity by adding complexity rather than taking away complexity. Another way I think of it is in terms of the cost of those displaying left-side qualifiers. One cost is that they slow down finding the function name. Another cost is that by causing us to put |
I like this! The border-top highlight feels a bit weird, but not that weird (maybe we also need a border-bottom? idk) The only "complaint" I have about this is that the entire bar is the collapse toggle, but some parts of it are links, so if you click wrong it doesn't toggle and instead takes you elsewhere. I think this is fine, it's just a mistake I immediately made after opening the page, and no doubt others will to. But it feels like that's a mistake you make once, and I don't know how to fix this problem otherwise. |
foo()
I suggest using |
Yeah, that makes sense, but it seems rather "clever" in that it requires some thought before it makes sense. Idk. |
This behavior actually crept in somewhat by accident during the toggle refactor. Since the whole bar is part of the I think the right fix here is to add a JS event handler for clicks on the summary that cancels the default action, so clicks in places other than the |
Ah. Honestly the entire bar being the toggle does make some sense. But also fine with that not being the case as long as the +/- are always visible |
Thanks for all the feedback on this! I'm taking a small break from rust dev so I'm going to close this for now to keep the PR list clean, but I hope to keep working on it when I get back. The main remaining issue is that the emphasis on the method name in the overhead highlighting doesn't work right when there is an attribute, because the attribute gets displayed above the function: As of #86277, that will be a rarer occurrence, but we can still see attributes on methods in the case of Also of course if anyone is really into this change and would like to push it forward before I have a chance to, you are more than welcome! |
This is really more of a demo than a PR, to see if folks are interested in a significant design change like this.
I've heard multiple people say they feel that methods in rust documentation are not "scannable." In other words, it's hard to run your eyes down a page looking at all the method names to find a specific name, or to see if there's a name that matches what you're looking for.
Part of that is that there's a lot of stuff to the left of the method name, so the method name is not always in the same place. Part of that is that there's not a clear visual delineation between the end of one method's documentation and the summary of the next method.
In this demo I removed the
[-] pub fn
from the beginning of each function. My thinking is that[-]
can be shown just when it needs to be. "fn" is implicit in the fact that we're in a section full of methods (and also the parentheses and arguments are a great hint that we're looking atfn
s)."pub" is usually implicit since we're looking at documentation. There's the issue of
--document-private-items
, but we can solve that by marking the private items differently, rather than always marking public items so the private items can be noticed by their lack of "pub".I've also highlighted the methods with a border-top and a light grey background-color (same as the color on examples). For this I took inspiration from hexdocs (https://hexdocs.pm/phoenix/Phoenix.html#json_library/0) and Sphinx with the readthedocs theme (https://certbot.eff.org/docs/api/certbot.plugins.dns_common_lexicon.html). Both of those use a background color and a single border to make method headings stand out: hexdocs uses a border-left, and pydoc uses a border-top. I chose the same color we use as a border-right when a heading is
:target
(that is, when you've clicked on it from the sidebar or from a URL with a fragment).Anyhow, all sorts of feedback welcome. Do you see this as a problem in need of solving? Is this a good way to solve it? Are there other ways? I've intentionally not spent too much time polishing this PR, so if you don't wind up liking it don't worry that I'll be throwing too much work away.
/cc @jyn514 @Manishearth @GuillaumeGomez @Nemo157
Demo: https://hoffman-andrews.com/rust/scannable-methods/std/string/struct.String.html#implementations
Methods in default open position:
Methods in closed position: