Always display stability version even if it's the same as the containing item by GuillaumeGomez · Pull Request #118441 · rust-lang/rust (original) (raw)

Conversation

This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters

[ Show hidden characters]({{ revealButtonHref }})

@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

@GuillaumeGomez

@GuillaumeGomez

@rustbot rustbot added S-waiting-on-review

Status: Awaiting review from the assignee but also interested parties.

T-rustdoc

Relevant to the rustdoc team, which will review and decide on the PR/issue.

labels

Nov 29, 2023

@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

@rust-timer

This comment has been minimized.

@bors

bors added a commit to rust-lang-ci/rust that referenced this pull request

Nov 29, 2023

@bors

@bors

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

@rust-timer

This comment has been minimized.

@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

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

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.

image

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

@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

@rfcbot

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

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

📌 Commit a333572 has been approved by rustdoc

It is now in the queue for this repository.

@bors bors added S-waiting-on-bors

Status: Waiting on bors to run and complete tests. Bors will change the label on completion.

and removed S-waiting-on-review

Status: Awaiting review from the assignee but also interested parties.

labels

Apr 19, 2024

@bors

@bors

@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

netbsd-srcmastr pushed a commit to NetBSD/pkgsrc that referenced this pull request

Oct 13, 2024

@he32

This is based on the pkgsrc-wip rust180 package, retaining the main pkgsrc changes as best as I could.

Pkgsrc changes:

Upstream chnages:

Version 1.80.1 (2024-08-08)

Version 1.80.0 (2024-07-25)

Language

Compiler

Libraries

Stabilized APIs

These APIs are now stable in const contexts:

Cargo

Rustdoc

Compatibility Notes

Internal Changes

These changes do not affect any public interfaces of Rust, but they represent significant improvements to the performance or internals of rustc and related tools.

Version 1.79.0 (2024-06-13)

Language

Compiler

Refer to Rust's [platform support page][platform-support-doc] for more information on Rust's tiered platform support.

Libraries

Stabilized APIs

These APIs are now stable in const contexts:

Cargo

Rustdoc

Misc

Compatibility Notes

Version 1.78.0 (2024-05-02)

Language

Compiler

Target changes:

Refer to Rust's [platform support page][platform-support-doc] for more information on Rust's tiered platform support.

Libraries

Stabilized APIs

These APIs are now stable in const contexts:

Cargo

Misc

Compatibility Notes

Internal Changes

These changes do not affect any public interfaces of Rust, but they represent significant improvements to the performance or internals of rustc and related tools.

Version 1.77.0 (2024-03-21)

Compiler

Refer to Rust's [platform support page][platform-support-doc] for more information on Rust's tiered platform support.

Libraries

Stabilized APIs

Cargo

Rustdoc

Misc

Internal Changes

These changes do not affect any public interfaces of Rust, but they represent significant improvements to the performance or internals of rustc and related tools.

Labels