Rustdoc confusion: why are the method names gray and small?


#1

Hello. I was just having a bit of trouble reading the Rustdoc documentation and had a suggestion/observation to improve useability. I am still really new to Rust, but I am liking it a lot.

I was wondering if there was a reason why the Rustdoc documentation template seems to make the function or methods names gray and small font, while the argument lists return values are bolded and in seemingly a larger font. I am not sure if this is true for others, but for me this has the curious effect of making it hard to find the appropriate function or a specific purpose.

Case in point I was looking at the nalgebra documentation but overlooked a simple method to access individual elements from the matrix datatype. Haha, I actually lost some Stackoverflow reputation points over overlooking this method in the doco.

So just an observation that the Rustdoc template should make the method names or function names in larger font and unbold the rest.

Of course there might be a reason why the Rust developers chose the documentation style that the did. If there is some specific reason, I would appreciate someone sharing it.

I know the developers are busy working on more critical issues. But I figured some noobie feedback might be helpful.


#2

To be exact, do you mean this part, in red rectangle?


#3

Hello Bluss. Yeah, the red triangle is exactly right. I don’t know if anyone else has the same issue, but it makes it really hard to find the function names since the surrounding info is bolded–especially where there are a lot of arguments or type specifications, etc.

I don’t mean to start a thread with lots of opinions and stuff, which is always a risk on forums, eh. I just thought I would mention it to the developers since they might not be aware. Also, I was wondering if there is a way to customize my own rustdoc format when I generate documentation?

I totally get that this is probably not a priority. I was just working through the nalgebra documentation yesterday and was trying to find a way to reference an individual item in an nalgebra matrix. I could not find a reference to this or example in the nalgebra documentation. Then I posted a question on stackoverflow about referencing an individual element from an nalgebra matrix. The responder dinged me for not researching the documentation–which of course I had researched. So I was just wondering why I overlooked the index function, and I realized it was probably because of the function names are just hard to read.


#4

This might be an issue specific to certain hardware or wetware. On my nice desktop monitor, the function names look bold and high-contrast, and the “copper rose” color helps them stand out. But on one of my cheaper laptops, the names look much lighter and wash out very quickly at non-optimal viewing angles. Color blindness or other differences in vision could cause similar problems. A darker and more saturated color would probably work better for a wider range of viewers.


#5

I agree that the current styling isn’t the easiest to scan, and there are a bunch of open issues that discuss this problem or related problems that you may be interested in:

I think the problem is that after you’ve used rust docs for a while, you get used to the way info is displayed, and it doesn’t bother you as much anymore :frowning: So then the motivation to work on this problem is gone.


#6

Thanks @carols10cents and @mbrubeck for the comments. I am glad it is not just me who noticed it. As a newcomer to rust, I am still just trying to get used to the language mechanics and such. But hopefully the developers of Rust benefit from the input of newcomers as they try and make the language more accessible.


#7

Yes there is (at least on nightly) :slight_smile::

echo '.fnname { color: red !important; font-family: "Comic Sans MS"; }' > temp.css
cargo rustdoc --open -- -Z unstable-options --extend-css temp.css