rustdoc links point to function headers instead of the whole function starting from Rust 1.51

[pravic]

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:

• https://doc.rust-lang.org/src/core/bool.rs.html#37-40

Sometimes, to the first line of the header:

• https://doc.rust-lang.org/src/alloc/string.rs.html#1702

Sometimes, to the whole function:

• https://doc.rust-lang.org/src/std/path.rs.html#2087-2094
• https://doc.rust-lang.org/src/std/thread/scoped.rs.html#129-159

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:

rustc 1.62.0 (a8314ef7d 2022-06-27)
binary: rustc
commit-hash: a8314ef7d0ec7b75c336af2c9857bfaf43002bfc
commit-date: 2022-06-27
host: x86_64-unknown-linux-gnu
release: 1.62.0
LLVM version: 14.0.5

[pravic]

@rustbot modify labels: +T-rustdoc

[compiler-errors]

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?

[pravic]

@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.

[compiler-errors]

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. 🤷

[pravic]

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.