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

Author: bors

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() {

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;

src/test/rustdoc/issue-32374.rs

@@ -14,22 +14,28 @@
 #![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;
 
 // @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;