New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Always display stability version even if it's the same as the containing item #118441
Always display stability version even if it's the same as the containing item #118441
Conversation
Some changes occurred in src/librustdoc/clean/types.rs cc @camelid |
This is definitely going to make the standard library docs bigger. Let's see how much! @bors try |
This comment has been minimized.
This comment has been minimized.
…sion, r=<try> Always display stability version even if it's the same as the containing item Fixes rust-lang#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](https://github.com/rust-lang/rust/blob/e9b7bf011478aa8c19ac49afc99853a66ba04319/src/librustdoc/html/render/mod.rs#L949-L955). It was implemented in rust-lang#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](https://rustdoc.crud.net/imperio/display-stability-version/std/pin/struct.Pin.html#method.new). r? `@notriddle`
☀️ Try build successful - checks-actions |
This comment has been minimized.
This comment has been minimized.
Finished benchmarking commit (4d962f0): comparison URL. Overall result: no relevant changes - no action neededBenchmarking 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 Instruction countThis benchmark run did not return any relevant results for this metric. Max RSS (memory usage)ResultsThis 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.
CyclesThis benchmark run did not return any relevant results for this metric. Binary sizeThis benchmark run did not return any relevant results for this metric. Bootstrap: 673.033s -> 673.683s (0.10%) |
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. |
Yeah. I didn't think of that. Here's the output for 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 |
So about a 1.2% increase. That's not that bad I guess, but it's also not trivially small. |
@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. |
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. |
I think it's worth landing this. As their tend to be many methods on items in 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. |
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 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. |
Hm, that's a good point |
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. |
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. |
I was just quite confused by the missing stability annotation on a |
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. |
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 |
@GuillaumeGomez proposal cancelled. |
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. |
rfcbot seems to be glitching... @rfcbot reviewed |
🔔 This is now entering its final comment period, as per the review above. 🔔 |
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. |
@bors r=rustdoc |
☀️ Test successful - checks-actions |
Finished benchmarking commit (d1a0fa5): comparison URL. Overall result: ❌✅ regressions and improvements - ACTION NEEDEDNext Steps: If you can justify the regressions found in this perf run, please indicate this with @rustbot label: +perf-regression Instruction countThis is a highly reliable metric that was used to determine the overall result at the top of this comment.
Max RSS (memory usage)ResultsThis 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.
CyclesThis benchmark run did not return any relevant results for this metric. Binary sizeThis benchmark run did not return any relevant results for this metric. Bootstrap: 672.208s -> 672.762s (0.08%) |
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 |
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