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

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

3 files changed, 35 insertions, 14 deletions

diff --git a/src/librustdoc/html/render.rs b/src/librustdoc/html/render.rs
index 5253c1e9b27..e161f40b729 100644
--- a/src/librustdoc/html/render.rs
+++ b/src/librustdoc/html/render.rs
@@ -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() {
diff --git a/src/librustdoc/html/static/rustdoc.css b/src/librustdoc/html/static/rustdoc.css
index 0ca4f7ea36f..681d2354056 100644
--- a/src/librustdoc/html/static/rustdoc.css
+++ b/src/librustdoc/html/static/rustdoc.css
@@ -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;
diff --git a/src/test/rustdoc/issue-32374.rs b/src/test/rustdoc/issue-32374.rs
index dea73317e5e..b5edf535057 100644
--- a/src/test/rustdoc/issue-32374.rs
+++ b/src/test/rustdoc/issue-32374.rs
@@ -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 @@ pub struct T;
 // @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;