Always display stability version even if it's the same as the containing item

[GuillaumeGomez]

Fixes #118439.

Currently, if the containing item's version is the same as the item's version (like a method), we don't display it on the item.

This was something done on purpose as you can see here. It was implemented in #30686.

I think we should change this because on pages with a lot of items, if someone arrives (through the search or a link) to an item far below the page, they won't know the stability version unless they scroll to the top, which isn't great.

You can see the result here.

r? @notriddle

[rustbot]

Some changes occurred in src/librustdoc/clean/types.rs

cc @camelid

[notriddle]

This is definitely going to make the standard library docs bigger. Let's see how much!

@bors try
@rust-timer queue

[bors]

⌛ Trying commit a333572 with merge 4d962f0...

[bors]

☀️ Try build successful - checks-actions
Build commit: 4d962f0 (4d962f0f089466aec16928808dde2312d85fe7c1)

[rust-timer]

Finished benchmarking commit (4d962f0): comparison URL.

Overall result: no relevant changes - no action needed

Benchmarking this pull request likely means that it is perf-sensitive, so we're automatically marking it as not fit for rolling up. While you can manually mark this PR as fit for rollup, we strongly recommend not doing so since this PR may lead to changes in compiler perf.

@bors rollup=never
@rustbot label: -S-waiting-on-perf -perf-regression

Instruction count

This benchmark run did not return any relevant results for this metric.

Max RSS (memory usage)

Results

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-4.6%	[-4.7%, -4.4%]	2
All ❌✅ (primary)	-	-	0

Cycles

This benchmark run did not return any relevant results for this metric.

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 673.033s -> 673.683s (0.10%)
Artifact size: 313.38 MiB -> 313.38 MiB (-0.00%)

[Kobzol]

Hmm. The sizes are the same (https://perf.rust-lang.org/compare.html?start=abe34e9ab14c0a194152b4f9acc3dcbb000f3e98&end=4d962f0f089466aec16928808dde2312d85fe7c1&stat=size%3Adoc_bytes&tab=compile&nonRelevant=true&showRawData=true). But I guess that's expected, since non-std documentation doesn't actually contain these attributes (?). We should probably measure the size of libstd docs, but that's not included in the benchmarks at the moment.

[notriddle]

Yeah. I didn't think of that. Here's the output for ./x doc library/std, run on my machine:

michaelhowell@Michael-Howells-Macbook-Pro rust % du -hs doc-new doc-old
117M    doc-new
116M    doc-old
michaelhowell@Michael-Howells-Macbook-Pro rust % du -s doc-new doc-old 
240272  doc-new
237384  doc-old

Where doc-new is the version in this branch (a333572), and doc-old is from b29a1e0

[Kobzol]

So about a 1.2% increase. That's not that bad I guess, but it's also not trivially small.

[notriddle]

@rfcbot fcp close

I have to say it's not worth it. There's reasonable arguments for both perspectives, and I don't want to be flip-flopping back and forth.

[rfcbot]

Team member @notriddle has proposed to close this. The next step is review by the rest of the tagged team members:

• @GuillaumeGomez
• @Manishearth
• @Nemo157
• @aDotInTheVoid
• @camelid
• @jsha
• @notriddle

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[aDotInTheVoid]

I think it's worth landing this. As their tend to be many methods on items in std, users probably haven't seen the stability version of the containing item.

Also it feels weird and inconsistant that functions stabilized at the same time as the item have don't have a stability marker, but the rest do.

I think we should merge this.

[jsha]

I lean on the side of "close without action."

It's true that it's a bit weird and confusing to not have stability information in every possible place. And when I first noticed that I thought it was a bug.

But stability versions take up a notable amount of room in the UI, and if they are on every item in the standard docs, it will be harder to notice which ones are noteworthy. For instance, I think this PR would annotate every single method of String with 1.0.0, right? That's not very noteworthy.

And if someone does make a mistake and uses a method that is not stabilized on the older version of Rust they're using, because they didn't notice that the struct itself wasn't stabilized by that version, they will get a nice error that makes it pretty clear what the problem is.

[Manishearth]

Hm, that's a good point

[scottmcm]

For instance, I think this PR would annotate every single method of String with 1.0.0, right?

I wonder if that gives another alternative -- rather than "omitted is same as the type", it could be "omitted is 1.0", which might bring that size overhead back down a bunch again, if it was largely from old basics?

Still dunno if it's worth doing, though.

[Nemo157]

I also feel like I weakly fall on the side of landing this (maybe with the change to hide 1.0.0 annotations to reduce the size impact). I have been personally confused at the lack of annotations many times and feel like the consistency gain is worth it.

[RalfJung]

I was just quite confused by the missing stability annotation on a const fn: #121989

[GuillaumeGomez]

We (briefly) talked about it in the last rustdoc meeting. Some members of the team would actually like this feature to be merged, so more discussions will follow.

[GuillaumeGomez]

As discussed on zulip, seems like the majority of the rustdoc team would prefer to have this feature.

The original reason (in 2016, so very shortly after the 1.0) for not displaying the version in case it was the same as the parent's was because it was too much noise. At the time, it was much more common for the majority of sub-items to be from 1.0. Now there's a much wider spread of version numbers so the items which don't have a version number on them are probably the minority.

But also, since then, the number of items grew quite a lot and it's not rare to land on a page to a given item and then you need to scroll to the top to see the version of the parent item to see from which version it can be used if it was not marked.

For these reasons, I'll cancel the closing FCP and open a merge FCP instead.

@rfcbot cancel

@rfcbot merge

[rfcbot]

@GuillaumeGomez proposal cancelled.

[rfcbot]

Team member @GuillaumeGomez has proposed to merge this. The next step is review by the rest of the tagged team members:

• @GuillaumeGomez
• @Manishearth
• @Nemo157
• @aDotInTheVoid
• @camelid
• @jsha
• @notriddle

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[camelid]

rfcbot seems to be glitching...

@rfcbot reviewed

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[GuillaumeGomez]

@bors r=rustdoc

[bors]

📌 Commit a333572 has been approved by rustdoc

It is now in the queue for this repository.

[bors]

⌛ Testing commit a333572 with merge d1a0fa5...

[bors]

☀️ Test successful - checks-actions
Approved by: rustdoc
Pushing d1a0fa5 to master...

[rust-timer]

Finished benchmarking commit (d1a0fa5): comparison URL.

Overall result: ❌✅ regressions and improvements - ACTION NEEDED

Next Steps: If you can justify the regressions found in this perf run, please indicate this with @rustbot label: +perf-regression-triaged along with sufficient written justification. If you cannot justify the regressions please open an issue or create a new PR that fixes the regressions, add a comment linking to the newly created issue or PR, and then add the perf-regression-triaged label to this PR.

@rustbot label: +perf-regression
cc @rust-lang/wg-compiler-performance

Instruction count

This is a highly reliable metric that was used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	0.3%	[0.2%, 0.3%]	2
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-0.2%	[-0.2%, -0.2%]	1
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	0.1%	[-0.2%, 0.3%]	3

Max RSS (memory usage)

Results

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	2.5%	[2.5%, 2.5%]	1
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	2.5%	[2.5%, 2.5%]	1

Cycles

This benchmark run did not return any relevant results for this metric.

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 672.208s -> 672.762s (0.08%)
Artifact size: 315.30 MiB -> 315.24 MiB (-0.02%)

[lqd]

This is rustdoc change that shouldn't cause the regex-opt regressions; let's see how this noise does in the future but in the meantime, @rustbot label: +perf-regression-triaged