Improved rustdoc rendering for unstable features #38843
Conversation
|
(rust_highfive has picked a reviewer for you, use r? to override) |
|
"This is a nightly-only experimental API" might be better. Changing the text (or even the fact that it is displayed) based on the version of the docs being built is also interesting. We should also be greying-out unstable methods everywhere, not just in the module list. |
“Unstable API”? I like the use of |
|
Part of the point was to remove the word "unstable" as it can cause confusion. |
|
Nice! I just saw your suggestion to open an RFC… this seems more straightforward. 😄 It's getting a bit wordy, but perhaps: " |
|
"unstable API" seems fine for me, but otherwise I don't have much preference in here. Big 👍 for me. This is a huge improvement and I'm really looking forward to it. |
|
@Manishearth This is a great change. I agree that moving away from the stable/unstable terminology will reduce confusion. Adding "nightly-only" is probably a good idea, for maximum clarity. cc @brson |
|
I too prefer experimental to unstable. It makes us sound like scientists. I would prefer to add some mention of nightly as well. /me wants a lab-coat |
|
I'm disappointed that there is no Erlenmeyer flask emoji. Microscope (🔬) exists, and it is supposed to combine with person emojis to create scientist emojis, but that doesn't work on many fonts right now. So something like:
is probably what we're settling on. |
|
FWIW, the |
|
I don't see that being used in the docs anywhere? I noticed that not all APIs have extended unstable reasons, so I should probably fix up this PR to handle that (e.g. http://manishearth.github.io/rust-internals-docs/syntax/parse/fn.raw_str_lit.html) |
|
But it's not actually appearing.... hmmmm |
|
@Manishearth Microscope is way cooler. 😄 |
|
🍼 Baby Bottle (U+1F37C) 🍼 This is an experimental API, available only on Rust nightly builds. |
|
|
|
@Manishearth I can't really make out that it is a microscope. :( I sort of like baby bottle. =) |
|
Not really better with the baby bottle
Note that emoji will render differently on different platforms. What we should do here is just make the font size a bit larger. |
|
How does a font size of 1.5em sound?
|
|
@nikomatsakis: And I prefer the microscope. Should we vote? :p @Manishearth: I prefer with 1.5em, indeed (but it seems a little bit too big). |
|
(I'll need to update the tests too, so don't directly r+ this, just mention "r=me" or whatever. I won't update them now since we have to yet settle on the exact way to display this) |
There is EmojiOne. |
|
Microscope is fine with me. The bigger size looks mildly better. |
|
Are we still in the bikeshed phase for this PR or should I start cleaning up the tests so that we can land this? |
|
From my point of view, we're in the details now. Text shouldn't change and it seems microscope is the preferred icon. Maybe wait confirmation from others and then clean up? |
|
@Manishearth let's ship! Agreed on larger-sized microscope. |
|
Updated tests. |
|
Then it's all good. Thanks! @bors: r+ |
|
📌 Commit 0a1c9ae has been approved by |
|
⌛ Testing commit 0a1c9ae with merge 8a4f77e... |
|
💔 Test failed - status-appveyor |
|
@bors: retry
* hang in compiling librustc?
…On Tue, Jan 10, 2017 at 6:07 AM, bors ***@***.***> wrote:
💔 Test failed - status-appveyor
<https://ci.appveyor.com/project/rust-lang/rust/build/1.0.1489>
—
You are receiving this because you are on a team that was mentioned.
Reply to this email directly, view it on GitHub
<#38843 (comment)>, or mute
the thread
<https://github.com/notifications/unsubscribe-auth/AAD95B3IKXzfqMjYmgsxo9Lqilan_7Qaks5rQ5C3gaJpZM4LbYO8>
.
|
|
⌛ Testing commit 0a1c9ae with merge d6b927d... |
Improved rustdoc rendering for unstable features This replaces "unstable" with "this is an experimental API", and uses a `<details>` tag to expand to the reason. The `<details>` tag renders as a regular div (with the details show) on browsers which don't support it, On browsers which do support it, it shows only the summary line with an expandy-arrow next to it, and on clicking it the details will turn up below it. This is somewhat a strawman proposal. The main issue is that we need to improve our messaging around unstable APIs. Since they turn up in the docs, we should be clearer that they are experimental (and perhaps add something about nightly-only). I'm making this PR to kickstart discussion on this. Example rendering: http://manishearth.github.io/rust-internals-docs/std/io/trait.Read.html#method.chars <img width="375" alt="screen shot 2017-01-04 at 10 15 37 pm" src="https://cloud.githubusercontent.com/assets/1617736/21670712/5a96c7de-d2cb-11e6-86a6-87f70818d634.png"> expands to <img width="799" alt="screen shot 2017-01-04 at 10 15 43 pm" src="https://cloud.githubusercontent.com/assets/1617736/21670714/5db88bb4-d2cb-11e6-8fcc-5cf11d198b75.png"> cc @steveklabnik @jdub
|
☀️ Test successful - status-appveyor, status-travis |
This replaces "unstable" with "this is an experimental API", and uses a
<details>tag to expand to the reason.The
<details>tag renders as a regular div (with the details show) on browsers which don't support it, On browsers which do support it, it shows only the summary line with an expandy-arrow next to it, and on clicking it the details will turn up below it.This is somewhat a strawman proposal. The main issue is that we need to improve our messaging around unstable APIs. Since they turn up in the docs, we should be clearer that they are experimental (and perhaps add something about nightly-only). I'm making this PR to kickstart discussion on this.
Example rendering: http://manishearth.github.io/rust-internals-docs/std/io/trait.Read.html#method.chars
expands to
cc @steveklabnik @jdub