Open lambda opened 5 years ago
Only show some or all of these elements if items are being hovered over
Hover is not necessarily obvious on touch devices.
perhaps immediately to the right of the first line of the declaration, rather than right-justified
Javadocs put this information at the bottom of descriptions as documentation-annotations.
Hover is not necessarily obvious on touch devices.
Good point. I'll modify the suggestion about hover to only have it change contrast rather than displaying items.
Javadocs put this information at the bottom of descriptions as documentation-annotations.
Yep. Python also puts them in the description (though its docs are written manually, not generated by a doc generator). cppreference (also manually written, not automatically generated) puts them next to the name of the item in question in tables of contents, and next to the declaration on the details page. Many others I've looked at don't include this information in an easily accessible manner, as far as I can tell. I do appreciate that rustdoc tries hard to report version availability, though it's missing on a lot of items, but I think it gets slightly more prominence than it should.
This seems like it is mostly a workaround for the fact that many interfaces were stabilized before
impl Trait
existed, which means that there are concrete types being returned when what the user of the interface is interested in is the trait implemented by the return value.
No, that's not why. We still don't use -> impl Trait
for e.g. Iterator
even when we can. Due to conditional implementations, -> impl Trait
can eliminate capabilities that you'd otherwise have. For example, we have impl<I: Clone, F: Clone> Clone for Map<I, F>
but if you return -> impl Iterator<...>
then the compiler doesn't know that.
@Centril Thanks for the correction, updated to hopefully be more accurate.
Here's a quick mockup of what this might possibly look like:
The body font I've used is Source Sans Pro which complements the Source Code Pro that the docs are already using for code blocks.
The length of paragraphs and list items is limited separately from code blocks and headings, I feel that this provides an optimal experience especially when dealing with computer generated content like the main content heading.
The "Show Declaration" box has been styled as though it was content, and when collapsed shows the type and name but no fields that are defined.
I also moved all of the collapse toggles and header links into the far left column for the sake of consistency.
Using more standard disclosure controls (such as ⊞ and ⊟, or ▶︎ and ▼), and prose like source instead of [src], may help.
Would it make sense to switch to <details>
?
@measlytwerp Thanks for putting that together! I like the mockup a lot; it addresses may of my points. It does still have the [src]
on the right for the traits, but it looks like a big improvement.
Would it make sense to switch to
<details>
?
You could switch to using <details>
here, but you'd still need to customize the styling because the browser default style might be a little too heavy. I think whether you switch to <details>
is more of an implementation issue, and question of accessibility to screen readers, which should also be considered but I have nowhere near the expertise to comment on that.
Review of specific thoughts on @measlytwerp's mockup:
[src]
link makes it feel a bit unbalanced. Moving the rest of the [src]
links inline and making the search bar width match the new narrower content could help.<code>
definitely helps out a lot with the clutter[src]
link at the bottom could also be put inline and in prose like the one at the top.Overall, really like the mockup; I think it addresses a lot of the issues, and really looks like a big improvement. Thanks @measlytwerp for doing that!
Any chance it could be turned into something that could be browsed live to see how it works on more docs?
I think the only practical way to do that would be to do the work and modify rustdoc as there were a lot of underlying markup changes I had to make in order to get the styling to be reasonable.
I'll make a start on it now.
One question that I don't see a clear answer to, what browser compatibility are we looking for? I see that there's currently a message in the docs about IE8 not being supported, but what about IE9 and 10?
Edge, Chrome, Safari and Firefox shouldn't be a concern.
I don't know if there's a specific policy, but Rust offers Tier 1 support for Windows 7 and up, and IE 11 is the latest browser available for Windows 7. Based on global usage share numbers, I doubt that there's much of a call for earlier versions of IE especially among a technically oriented crowd, but I think that targeting IE 11 is probably a good idea unless there's a good reason not to.
Yeah IE11 is fine.
I'll try and put what I've done so far up before I sleep tonight.
Here's my working branch, and I've also made a GitHub pages site out of the docs.
I'll continue working on this tomorrow.
1: https://github.com/measlytwerp/rust/tree/rustdoc-reskin 2: https://measlytwerp.github.io/rustdoc-reskin/std/
Interesting, our earlier discussions are currently dated as being in the future. I thought GitHub had swallowed my post.
Ooh, wow, the timestamps are off. And they were off in the other direction when I checked earlier today; shortly after posting the exchange about IE, they were dated 5-8 hours ago, now some are in the future. GitHub seems to be having some issues.
https://twitter.com/githubstatus/status/1126171459255185414
Took a quick look and I like the start. Definitely a lot of rough edges, but it looks a lot cleaner already.
I've gotten quite a bit more done today.
You'll notice in particular that there's now a line drawn along the side of the screen marking where collapsible sections start and end, it's very faint so as to not interfere with reading. I've done this because I kept getting lost when collapsing things because without nesting there's no way to know when something ends.
Another thing of note is that headers in markdown or generated by the docs are no longer linked. The headers next to collapsible controls were linked, which was very confusing. Instead I've added a #
link after each header.
The rustdoc code is quite a mess, but I'll continue tomorrow.
Got a lot more small bits finished today, things are looking a lot nicer.
It'd be good to get some feedback on this work, I've had some elsewhere that's been mostly positive, but constructive criticism is wanted.
This is being broken out of #59829 to provide smaller, actionable items that can be independently discussed and worked on.
A review of rustdoc for accessibility, especially for dyslexia and attention disorders, finds that there are a number of visually distracting elements in rustdoc which can draw attention away from the main content. These should be considered along with the other issues mentioned in #59829 about the overall effect of a number of distracting elements on the page.
Items in rustdoc can have a number of controls and auxiliary information associated with them, which can be quite prominent and distracting. These should either be eliminated, or made less prominent so that the reader can more easily follow the main content and only notice them when they need to find them.
At the top of a page, we see several controls that are larger and more prominent than the main text. The top of page
[-]
and[src]
controls are larger and bolder than the body text. The version number is a bit smaller and lower contrast, but unexplained what it means.Immediately above the main text is a "Show declaration" disclosure which is lower contrast, but larger, than the main text, and the main text itself also has a disclosure control immediately to its left, crowding it.
impl
blocks have disclosure controls indicating a nesting relationship, even though the headings themselves don't, which leads to some distracting spacing. They also can have a number of closely spaced prominent[src]
links and version numbers. The[src]
links are a slightly larger font size (17px) than the content (16px).There are also a variety of different sizes of these disclosure controls, which don't match the logical hierarchy.
There's an additional "important traits" control that appears on some methods which indicates some important traits implemented by the return value of the method. This allows showing traits that are implemented by the return type for thing like iterator adapters, where the user usually cares more about the trait implemented than the concrete type. This adds another UI element which is high contrast, doesn't match in size, and has a different way of disclosing hidden information. Previous discussion of this design is present in the implementation issue, #45039.
There is going to need to be a balance between reducing or eliminating the visual impact of these elements, while still making the same information easily discoverable for those who need it.
Here are a few suggestions about how we might be able to achieve this.
[+]
,[-]
, and[src]
could be mistaken for some kind of source code annotation; the brackets are also very eye-catcing. Using more standard disclosure controls (such as⊞
and⊟
, or ▶︎ and ▼), and prose likesource
instead of[src]
, may help.