Add underline hints to the docs. Exclude obvious things.

[mdinger]

Links:

solid underline
dashed underline
colored primitives and aliases

---

Original post:

Here's a PR which fixes #15307

I hosted a version (std::vec) but I must have messed something up because they don't work perfectly (but you can still see how the line styling looks fine). I don't think jquery loaded properly but I'm not sure why.

Note: I don't particularly like this as it is. Many of the links already kinda look like links. It's mainly the primitives which don't look like links because they're black.

For example, below you can probably tell the functions and the structs are links but usize, who knows without the underlining. The underlining also basically ignores the coloring that already exists and kinda feels inconsistent.

---

As an alternative, I'd consider trying something else. If you look at this picture, the first 5 colors are the colors currently used for link highlighting (I think). I'd consider trying something like number 6 for primitives to see if it makes this issue much better as an alternative to this PR.

Note: If I could figure out how to tell rustdoc to add a class='primitive' to each primitive element, this would be easy to test out but I haven't figured that out yet.

[rust-highfive]

r? @steveklabnik

(rust_highfive has picked a reviewer for you, use r? to override)

[mdinger]

r? @steveklabnik If you like this, feel free to merge. I think fixing the colors would be better but I couldn't get it to work and I'm not interested in spending lots and lots of time getting it to work.

[steveklabnik]

Yeah, given that this is a style change which affects everyone, I'd like to get some more feedback.

[iliekturtles]

I think the underline looks good and provides better accessibility for color-blind users.

For reference here is a screenshot with the color changed:

[alexcrichton]

I also think the underlines are pretty nifty!

[gkoz]

In my opinion dotted or dashed underlines imply a popup that opens on hover or some other same page interaction, using them for links is confusing. Subjectively it adds even more visual noise than the good old simple underline.

[ghost]

I agree with @gkoz; I like the highlighting, but the dotted underlining immediately makes me think of hover text, which is confusing when they're actually links.

[lambda]

I think the underlines add a lot of visual noise. If you look at something like the Iterator trait, it makes an already very busy page even busier.

I would very much prefer just making primitives a color other than black. I am not colorblind, so I can't make a judgement about how distinct the colors are, but I believe that for the most common types of colorblindness, the links would still be distinguishable from regular text, just not from each other. Even though I am being able to tell apart the colors, I don't actually know what the different colors mean, so I just equate color with links in the documentation, which should be fine for colorblind users as well.

[mdinger]

Added a version with solid underlines and dashed underlines. The site mostly works correctly now. Apparently it's picky about how it's copied over.

[mdinger]

I'd prefer to color them too but I haven't figured out how to inject the class into the HTML yet. Aliases also need coloring.

[bstrie]

I like the underlines, and I don't mind that they're dashed.

@lambda, I think the fact that that page looks busy is ultimately caused by a lack of proper line spacing.

[ghost]

+1 for the solid underlines.

[mdinger]

Added a version which colors primitives and types instead of using underlines. In particular, see io::Seek for aliases. std::vec::IntoIter seems like another decent example.

My preference is towards something more like this rather than underlining (interestingly, the link for a tuple may only be the opening part ( but not the ) (see the return type here)).

Of note, macros are still black (it should probably also be fixed...). Also, there is no consistency between code highlighting and link highlighting (maybe it doesn't matter but it's at least worth noting).

[mdinger]

Colored now colors macro links too. I'm not sure the link colors are ideal but I think they will be easy to distinguish. They look mostly fine to me.

[defuz]

What about the colored version that underlines the links only when they are hover?

[mdinger]

I don't really want to upload every permutation possible. I'm just trying to make it a little easier for people who want to view a couple themes.

[defuz]

I understand that. I just wanted to add suggestions of how to get rid of the noise. There are nothing good in underlining if 50% of the text are underlined. We spend a lot of time reading the documentation. Intuitively is good, but it should not conflict with convenience.

[photino]

I like the colored version. It is consistent that all links will be colored. Two many underlines in a page are quite annoying.

By the way, could you also remove the border-bottom style of navs:

nav {
    border-bottom: 1px solid #e0e0e0;
}

This style is redundant and sometimes confusing (see the left aside nav of num-traits as an example).

[mdinger]

@defuz Oh, I thought you were being smart by suggesting I just keep uploading more and more.

Anyway, I'll wait to see if there is a consensus on anything before I do anything else.

[arthurprs]

Underlining adds some noticeable noise to the page, extra coloring seems great though.

[lambda]

Thanks for doing the colored version! I like that a lot better than the underlined version.

One thing I wonder is whether having all of the different colors for the different types of links is all that useful. In the current example, there are different link colors for functions/methods, traits, structs, enums, primitives, type aliases, modules, and macros. I know that I can't keep track of the mapping of that many colors, but I also don't really need to, since it's generally obvious from context what I'm looking at, or I can just follow the link to find the information I need.

In particular, I'm wondering if might make sense to collapse all of the concrete types (structs, enums, primitives, and type aliases) down to a single color, since I'm not usually all that interested in which of those mechanisms is used for defining a type when I'm just reading and API that's using them, and if I do want to find out, I can just click through. Distinguishing between concrete types, traits, functions/methods, modules, and macros seems like a smaller, and more useful, set of distinctions to make.

Are these fine-grained color distinctions something that other people find useful?

[mdinger]

@defuz I can upload ones with underlining on hover if/when something converges. It seems sensible to try and easy to do.

@lambda FWIW, the playpen doesn't distinguish by color between struct, enum, type, and primitive however, in the playpen there isn't a huge tendency to show every type signature for the module all clumped together as in say std::iter::Iterator.

You could erase the distinctions and it would look something like this (wouldn't have to be green though I suppose):

This basically seems to mellow the page out and highlights that parameters are types, rather than a conglomeration of various unknown things.

Pages with headers are also simplified:

This seems a little odd but I don't think it's terribly problematic. Originally I didn't really like the loss of multiple colors but I'm warming to it a little. Don't currently have a strong opinion either way yet.

[lambda]

Yes! That's exactly what I was thinking of, and I like how it works out in practice.

I don't have any preferences on the exact color scheme, but I do like the balance provided by having all of the links be colored, but only three different colors to distinguish different kinds of links.

[steveklabnik]

I plan on merging #29264 instead of this.