Rust API doc style is sometimes confusing

[edermi]

While browsing the API documentation today, I found out that it's really hard to find a specific information with just scrolling the page.

For example, try to find fn last in the Vec documentation by just scrolling the page. This is really hard because of all the "Example"s written in bigger letters catching the eye. A little picture for those who don't want to try:

In comparison, try to find math.sqrt() in the Python math documentation by just scrolling the page. To me, this seems easier because of the clear highlighting of the function names and the indentation of the explanations. (Don't get me wrong, the python documentation isn't perfect, too)

This issue is not really big, but programmers are humans and they're often in a hurry. A clearer structure/design of the API documentation would improve readability and help people looking for specific features without knowing the precise function name in Rust.

[gsingh93]

I agree this is a issue I'd like to see fixed. Related: #15642

[cyplo]

Hi ! It seems like a very cool idea for improving the docs !
I saw you removed the headings already, @bluss - awesome ! I was wondering - @edermi, @gsingh93 - do you need the function names to be change to more visible as well, or is it good as it is, just with the headings removed ?

thanks !

[gsingh93]

The only thing I want from the docs at this point is to have an alphabetized list of all the function names at the top. To get a list of all function names, I can click the [-] button, but it still takes longer for me to visually find a function name in an unsorted list.

[cyplo]

Thanks a lot ! @bluss - are you interested in taking this work further, do you think it's best to be finished by someone else ?

[bluss]

@cyplo I haven't done anything for this in rust I think. I'd love to see any kind of improvement, feel free to work on it.

[cyplo]

Alrighty - I will take a look there and see what I can do to improve the docs in a way suggested here, to have the function names more easily browseable/scannable. Thanks !

[QuietMisdreavus]

It looks like the doc style has changed a fair amount since this issue was last touched. Would you still consider this a problem? Do we want to morph this into "add a method listing separate from the full doc listing" instead?

[edermi]

I think the issue is still there. I just scrolled the std::vec::Vec page and the size and color of "Example" and panics are still catching my eyes, distracting from the methods. What's the issue with just chanigng the font size to be smaller than the actual function name? Example is wrapped within a <h1> tag while the more relevant content is <h4>....

Did you ever consider to collapse the examples? This may help to skim over a page to find the desired function. Examples can be shown by expanding the collapsed field.

[QuietMisdreavus]

The doc text can be collapsed all at once with the [-] button, either beside each item or at the top of the page to toggle everything. (Adding a settings page to make "collapse all" the default, among other things, is already an issue: #18167) Collapsing specific headings within each block would require parsing the arbitrary text for these headings ahead of time, so we could inject "docblock" wrappers around the sections in question. Changing the font size for headers and function signatures, on the other hand, is a small CSS change, and can be previewed without even generating new docs:

This just shrinks the headings inside doc blocks a little. Is this sufficient, or are more tweaks necessary?

[edermi]

I changed the heading type of "Example" to h5 and changed the CSS temporarily for
.docblock.h5 to not be solid. You can compare my changes in the attached image, I think the first one is far more friendly to read and it's really just a small change

[steveklabnik]

The size of the heading vs the size of the code sample looks really really strange to me, though that may just be because I've stared at rustdoc's output so much.

[QuietMisdreavus]

The problem with making it an h5 is that that requires modifying the markdown as it's processed: each chunk of documentation is processed separately. We can continue to shrink the font for <h1>s inside these docs, though, since those can be handled separately in the CSS.

(Also that h5 example is kinda hard to read on my screen? It's smaller than the surrounding text, and not even styled into the same font as the other headings.)

[edermi]

My screenshot is probably not the best solution, I guess you will find a better one. All I want to say is that by now, Examples and Code are really distracting and functions are not highlighted enough. Maybe it's just that I'm used to Python, but Rust was by now the only language where I noticed that scrolling over the documentation in order to find a function is quite hard because there is IMO less/distracting optical structure compared to others. (see also screenshots in my first post)

If I'm the only one that is affected by this, feel free to close the issue, I don't want to waste your development resources on CSS discussions.

[bluss]

It's certainly worth fixing. crates itertools and ndarray don't use # Examples headings, because they are too big and distracting. The exceptions are mostly doc items that have the whole page for themselves.

This is not just about examples, it's all headings, right? Common ones are Panics, Safety, Examples.

I think shrinking those headings to current h3 size already is a big improvement -- we can try something like that?

[QuietMisdreavus]

Here's a sample that shrinks h1s inside doc blocks to 1em, which is what h3s are right now:

There may need to be more finessing required if we don't want them to shrink on top-level docs, but for now i can sketch this out without much fuss.

(EDIT: i don't consider small CSS changes to be a waste of time, because it's a relatively small amount of effort for a sizeable reward. Plus i'm just going through all the rustdoc issues at this point and wanted to make sure this was triaged properly. If i can close it in the process, then i still consider that a win!)

[edermi]

I think this can still get better with more fine-tuning, but your suggestion is already a big improvement @QuietMisdreavus, thanks!

[QuietMisdreavus]

Just to get a sketch together, I've rendered a set of std docs at https://tonberry.quietmisdreavus.net/std-17193/std/index.html - I split out the CSS rules to make sure that headings in the topmost docs are the same as now, but headings elsewhere (under methods, traits, impls, etc) get shrunken to the size in that screenshot. Expanding the function-signature headings is another easy change, if you'd like that too.

[QuietMisdreavus]

I just opened #43602 with this CSS change.