docs: fix the order of items in method headers for screen reader users

[ahicks92]

I think this is the right repository. If it's not, I'd appreciate being directed to the right place.

Rustdoc has begun showing the version at which a function was introduced on some methods. I'm not sure if this was introduced in 1.8.0 or if more methods were marked up, so I'm not sure how old this behavior actually is.

Unfortunately, these headers are horrible for screen reader users (i.e. me) because of the order that screen readers read the elements. Getting headings right is important because most screen reader users navigate by them. When I want to see what's available, I just keep tapping next header and hey, "fn foobar".

By the behavior without version numbers and using actual methods from the docs, screen readers see:

fn is_empty(&self) -> bool [−]

This is good because I get the function name first. I can simply keep going down the page very quickly, stopping at whatever looks interesting or whatever I'm looking for.

But by the new behavior:

1.6.0 [−] fn drain<R>(&mut self, range: R) -> Drain<T> 

The most interesting piece of information is fn drain, but a screen reader user has to listen to (writing as text for illustration) "one point six point zero left bracket minus right bracket" first. This is significantly longer than the actual interesting information.

If I had to estimate how much slower I go on pages that use these heavily, I'd have to say at least 2x.

Looking at it in firebug, it appears that the difference is simply that the first header puts the code element in DOM order before the collapsing link, but the second header puts the since and collapsing link before the code. Looking at it with the other tools in my toolbox, it appears the other headers do actually put the collapsing link first visually with CSS, but I am unsure if this is truly the case. My tools for actually telling what CSS does are limited.

I can't fix this myself because any change I might make has roughly a 50/50 chance of breaking the CSS and I obviously can't tell if I did or not. If new CSS is needed (which I suspect) then I can't do anything. There is a reason I avoid web programming.

[GuillaumeGomez]

I see the version number on the right and the "[ - ]" on the left.

[mitaa]

That's because of the css, but the actual html element ordering is "version number, [-], function".
(the screenreader presumably doesn't care about the css (?))
(I have a simple fix ready - will check and submit later today)

edit: (sorry @GuillaumeGomez , I understand now..)

[ahicks92]

yeah, the screen reader behavior is different. Some CSS is respected, some isn't. There is no list of things that will and won't work.
If you can post a link to generated docs or something, I'll go over it. This should be an easy fix, I just can't be the one to do it for really obvious reasons.

[GuillaumeGomez]

I'll try to take a look this week-end if you want.