mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Auto merge of #38843 - Manishearth:proposed, r=GuillaumeGomez

Browse Source 
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
This commit is contained in:
bors 2017-01-10 21:16:06 +00:00
commit d6b927dd91
3 changed files with 35 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
src/librustdoc/html/render.rs
View File

@ -1871,8 +1871,10 @@ fn short_stability(item: &clean::Item, cx: &Context, show_reason: bool) -> Vec<S
};
if stab.level == stability::Unstable {
let unstable_extra = if show_reason {
match (!stab.feature.is_empty(), &cx.shared.issue_tracker_base_url, stab.issue) {
if show_reason {
let unstable_extra = match (!stab.feature.is_empty(),
&cx.shared.issue_tracker_base_url,
stab.issue) {
(true, &Some(ref tracker_url), Some(issue_no)) if issue_no > 0 =>
format!(" (<code>{}</code> <a href=\"{}{}\">#{}</a>)",
Escape(&stab.feature), tracker_url, issue_no, issue_no),
@ -1882,17 +1884,22 @@ fn short_stability(item: &clean::Item, cx: &Context, show_reason: bool) -> Vec<S
(true, ..) =>
format!(" (<code>{}</code>)", Escape(&stab.feature)),
_ => String::new(),
};
if stab.unstable_reason.is_empty() {
stability.push(format!("<div class='stab unstable'>\
<span class=microscope>🔬</span> \
This is a nightly-only experimental API. {}</div>",
unstable_extra));
} else {
let text = format!("<summary><span class=microscope>🔬</span> \
This is a nightly-only experimental API. {}</summary>{}",
unstable_extra, MarkdownHtml(&stab.unstable_reason));
stability.push(format!("<div class='stab unstable'><details>{}</details></div>",
text));
}
} else {
String::new()
};
let unstable_reason = if show_reason && !stab.unstable_reason.is_empty() {
format!(": {}", stab.unstable_reason)
} else {
String::new()
};
let text = format!("Unstable{}{}", unstable_extra, MarkdownHtml(&unstable_reason));
stability.push(format!("<div class='stab unstable'>{}</div>", text))
stability.push(format!("<div class='stab unstable'>Experimental</div>"))
}
};
} else if let Some(depr) = item.deprecation.as_ref() {
let note = if show_reason && !depr.note.is_empty() {

8
src/librustdoc/html/static/rustdoc.css
View File

@ -535,6 +535,14 @@ body.blur > :not(#help) {
display: inline;
}
.stab summary {
display: list-item;
}
.stab .microscope {
font-size: 1.5em;
}
.module-item .stab {
display: inline;
border-width: 0;

12
src/test/rustdoc/issue-32374.rs
View File

@ -14,14 +14,14 @@
#![unstable(feature="test", issue = "32374")]
// @has issue_32374/index.html '//*[@class="docblock-short"]' \
// '[Deprecated] [Unstable]'
// '[Deprecated] [Experimental]'
// @has issue_32374/struct.T.html '//*[@class="stab deprecated"]' \
// 'Deprecated since 1.0.0: text'
// @has - '<code>test</code>'
// @has - '<a href="http://issue_url/32374">#32374</a>'
// @matches issue_32374/struct.T.html '//*[@class="stab unstable"]' \
// 'Unstable \(test #32374\)$'
// '🔬 This is a nightly-only experimental API. \(test #32374\)$'
#[rustc_deprecated(since = "1.0.0", reason = "text")]
#[unstable(feature = "test", issue = "32374")]
pub struct T;
@ -29,7 +29,13 @@
// @has issue_32374/struct.U.html '//*[@class="stab deprecated"]' \
// 'Deprecated since 1.0.0: deprecated'
// @has issue_32374/struct.U.html '//*[@class="stab unstable"]' \
// 'Unstable (test #32374): unstable'
// '🔬 This is a nightly-only experimental API. (test #32374)'
// @has issue_32374/struct.U.html '//details' \
// '🔬 This is a nightly-only experimental API. (test #32374)'
// @has issue_32374/struct.U.html '//summary' \
// '🔬 This is a nightly-only experimental API. (test #32374)'
// @has issue_32374/struct.U.html '//details/p' \
// 'unstable'
#[rustc_deprecated(since = "1.0.0", reason = "deprecated")]
#[unstable(feature = "test", issue = "32374", reason = "unstable")]
pub struct U;