Rustdoc - display since version for stable items
#30686
Conversation
|
Yay! |
|
I would prefer if the text was less prominent: either greyed or with smaller font. It is too distracting at the moment for something that's so meta. |
|
@tshepang What do you think of this? |
|
@wesleywiser that's better, thanks |
|
I also have the sense that this is giving a great deal of prominence to a rather unimportant piece of information. One thing we could do is remove 'since' - this word doesn't convey any information every time it's repeated. This is also a new way to style stability information, and I already count two - See for example where stability of the element on the page is indicated by a colored box while stability of its methods is indicated by the word '[Unstable]' while fading out the text. It would be easier to understand that this and that are both types of stability information if they were styled similarly. |
|
@brson re 'since': I agree. Here's what it looks like without 'since': I think agree that adding yet another way to show stability information is bad. I'm having some trouble imagining what a common style might look like. One idea I had that might further minimize the visual noise would be to only show the version number when it is different than the containing object's version number. For example, the previous screenshot would look like this because |
|
I like the second option:
|
wesleywiser
force-pushed
the
rustdoc_display_since
branch
from
d2a35e5 to
5c5dab2
Compare
|
@wesleywiser I do like that idea of not displaying them when they are the same. With that I think I'm ok with trying this. |
|
I basically feel the same as @brson on this thread. Let's give it a try. Let me know when this PR implements that, and we'll merge after the release thursday, assuming you can update it before then. |
|
@brson @steveklabnik Will do. Sorry, I've been pretty busy lately but hopefully I'll have some time to work on it later this week. I'll post new screenshots when when I update the PR. |
|
No worries at all :) |
|
@wesleywiser ping! Any chance you've had the time to work on this? |
| @@ -339,6 +339,14 @@ impl Item { | |||
| _ => String::new(), | |||
| } | |||
| } | |||
|
|
|||
| pub fn stable_since(&self) -> Option<String> { | |||
There was a problem hiding this comment.
Can you use -> Option<&str> here instead? It should be enough since the string is only ever passed down. Change s.since.clone() to &s.since[..] too and update the other impacted code.
I think this change looks great otherwise.
wesleywiser
force-pushed
the
rustdoc_display_since
branch
from
5c5dab2 to
75acee2
Compare
|
@steveklabnik Great timing Steve! I think it's mostly working at this point (I looked over the generated docs and didn't see any glaring issues). I've updated this PR with the new code (and also implemented @bluss's suggestion). |
|
@bors: r+ okay, let's give it a try! 🎊 |
|
📌 Commit 75acee2 has been approved by |
Here's some screenshots after this change:    I tried to click through the `std` docs and make sure everything that can have stability attributes has it rendered but I'm probably missing some. I'd also appreciate any feedback on the css changes. I had difficulty getting the `since` labels aligning correctly for enum variants. If anyone has a better idea for that, I'd be glad to implement it. Fixes #27607
…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`
…sion, r=rustdoc 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`
…ustdoc Always display stability version even if it's the same as the containing item Fixes rust-lang/rust#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/rust#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`
…ustdoc Always display stability version even if it's the same as the containing item Fixes rust-lang/rust#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/rust#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`
…ustdoc Always display stability version even if it's the same as the containing item Fixes rust-lang/rust#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/rust#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`
Here's some screenshots after this change:
I tried to click through the
stddocs and make sure everything that can have stability attributes has it rendered but I'm probably missing some. I'd also appreciate any feedback on the css changes. I had difficulty getting thesincelabels aligning correctly for enum variants. If anyone has a better idea for that, I'd be glad to implement it.Fixes #27607