Repository navigation
rustdoc links point to function headers instead of the whole function starting from Rust 1.51 #100264
Description
Activity
I expected to see this happen: line numbers should cover the whole function
@pravic do you rely on this behavior? This is probably related to #93967 or similar work. I would prefer if we adjusted all item spans (i.e. those "Sometimes, to the whole function:") to point to just their headers. Thoughts?
@compiler-errors To answer that question we need to establish the intention of the source highlighting. Most documentation generators for other languages point to the first line of a function (a-la https://doc.rust-lang.org/src/core/slice/mod.rs.html#3442). In Rust we have quite got used to a higher level of documentation, including the source code span highlighting (a-la https://doc.rust-lang.org/src/core/slice/mod.rs.html#3442-3469).
The in-between behavior I find quite useless and confusing: https://doc.rust-lang.org/1.51.0/src/core/array/mod.rs.html#429-431.
So, I think it's better to either revert the original behavior (highlight the whole body), or to just point to the first line. The former would be ideal.
The in-between behavior I find quite useless and confusing
I'm not sure if I completely understand why this is confusing -- presumably you're clicking the link to the function's sources so you can investigate the the body of the function, which is right below. It's not like the lines that aren't highlighted are hidden.
Pointing to just the first line seems just as arbitrary of a decision as this current behavior.
In Rust we have quite got used to a higher level of documentation, including the source code span highlighting
I'm also not sure why this is a question of documentation quality. The choice of what lines to highlight doesn't obscure the fact that the sources are there and accessible, which I think really is the quality part of this documentation anyways. 🤷
I'm not sure if I completely understand why this is confusing
Because the mind remembers that it used to highlight the whole body. Now we see only partial highlighting and we are, like, "where's the rest of the function? ah, it's below the highlighting". Basically, it's a breaking change in UX.
Pointing to just the first line seems just as arbitrary of a decision as this current behavior.
Well, it's less confusing because it doesn't highlight - it just points to the function.
Original, before 1.51: https://doc.rust-lang.org/1.50.0/std/primitive.array.html#method.map points to https://doc.rust-lang.org/1.50.0/src/core/array/mod.rs.html#428-464
Regression, starting from 1.51: https://doc.rust-lang.org/1.51.0/std/primitive.array.html#method.map points to https://doc.rust-lang.org/1.51.0/src/core/array/mod.rs.html#429-431
I expected to see this happen: line numbers should cover the whole function
Instead, this happened: line numbers cover only the header of a function.
However, it's not stable. Sometimes, it points to the header only:
Sometimes, to the first line of the header:
Sometimes, to the whole function:
https://github.com/rust-lang/rust/blob/master/RELEASES.md#rustdoc-4
Version it worked on
It most recently worked on: 1.50
Version with regression
rustc --version --verbose: