Auto merge of #38244 - estebank:escape-reason-docs, r=ollie27

rustdoc: escape the deprecated and unstable reason text

Fix #38220.
Instead of the [current output](https://doc.rust-lang.org/std/boxed/trait.FnBox.html):

<img width="967" alt="incorrect unescaped unstable reason in docs" src="https://cloud.githubusercontent.com/assets/1606434/21021898/73121d42-bd2f-11e6-8076-8a5127dbc010.png">

display:

<img width="979" alt="escaped unstable reason in docs" src="https://cloud.githubusercontent.com/assets/1606434/21021876/52eb0f88-bd2f-11e6-9088-58bdc7d92328.png">

Author: bors

src/liballoc/boxed.rs

@@ -587,15 +587,15 @@ impl<I: FusedIterator + ?Sized> FusedIterator for Box<I> {}
 /// ```
 #[rustc_paren_sugar]
 #[unstable(feature = "fnbox",
-           reason = "will be deprecated if and when Box<FnOnce> becomes usable", issue = "28796")]
+           reason = "will be deprecated if and when `Box<FnOnce>` becomes usable", issue = "28796")]
 pub trait FnBox<A> {
     type Output;
 
     fn call_box(self: Box<Self>, args: A) -> Self::Output;
 }
 
 #[unstable(feature = "fnbox",
-           reason = "will be deprecated if and when Box<FnOnce> becomes usable", issue = "28796")]
+           reason = "will be deprecated if and when `Box<FnOnce>` becomes usable", issue = "28796")]
 impl<A, F> FnBox<A> for F
     where F: FnOnce<A>
 {
@@ -607,7 +607,7 @@ impl<A, F> FnBox<A> for F
 }
 
 #[unstable(feature = "fnbox",
-           reason = "will be deprecated if and when Box<FnOnce> becomes usable", issue = "28796")]
+           reason = "will be deprecated if and when `Box<FnOnce>` becomes usable", issue = "28796")]
 impl<'a, A, R> FnOnce<A> for Box<FnBox<A, Output = R> + 'a> {
     type Output = R;
 
@@ -617,7 +617,7 @@ impl<'a, A, R> FnOnce<A> for Box<FnBox<A, Output = R> + 'a> {
 }
 
 #[unstable(feature = "fnbox",
-           reason = "will be deprecated if and when Box<FnOnce> becomes usable", issue = "28796")]
+           reason = "will be deprecated if and when `Box<FnOnce>` becomes usable", issue = "28796")]
 impl<'a, A, R> FnOnce<A> for Box<FnBox<A, Output = R> + Send + 'a> {
     type Output = R;
 

src/librustdoc/html/markdown.rs

@@ -49,6 +49,8 @@ pub struct Markdown<'a>(pub &'a str);
 /// A unit struct like `Markdown`, that renders the markdown with a
 /// table of contents.
 pub struct MarkdownWithToc<'a>(pub &'a str);
+/// A unit struct like `Markdown`, that renders the markdown escaping HTML tags.
+pub struct MarkdownHtml<'a>(pub &'a str);
 
 const DEF_OUNIT: libc::size_t = 64;
 const HOEDOWN_EXT_NO_INTRA_EMPHASIS: libc::c_uint = 1 << 11;
@@ -58,6 +60,7 @@ const HOEDOWN_EXT_AUTOLINK: libc::c_uint = 1 << 3;
 const HOEDOWN_EXT_STRIKETHROUGH: libc::c_uint = 1 << 4;
 const HOEDOWN_EXT_SUPERSCRIPT: libc::c_uint = 1 << 8;
 const HOEDOWN_EXT_FOOTNOTES: libc::c_uint = 1 << 2;
+const HOEDOWN_HTML_ESCAPE: libc::c_uint = 1 << 1;
 
 const HOEDOWN_EXTENSIONS: libc::c_uint =
     HOEDOWN_EXT_NO_INTRA_EMPHASIS | HOEDOWN_EXT_TABLES |
@@ -220,7 +223,11 @@ thread_local!(pub static PLAYGROUND: RefCell<Option<(Option<String>, String)>> =
     RefCell::new(None)
 });
 
-pub fn render(w: &mut fmt::Formatter, s: &str, print_toc: bool) -> fmt::Result {
+
+pub fn render(w: &mut fmt::Formatter,
+              s: &str,
+              print_toc: bool,
+              html_flags: libc::c_uint) -> fmt::Result {
     extern fn block(ob: *mut hoedown_buffer, orig_text: *const hoedown_buffer,
                     lang: *const hoedown_buffer, data: *const hoedown_renderer_data) {
         unsafe {
@@ -383,7 +390,7 @@ pub fn render(w: &mut fmt::Formatter, s: &str, print_toc: bool) -> fmt::Result {
 
     unsafe {
         let ob = hoedown_buffer_new(DEF_OUNIT);
-        let renderer = hoedown_html_renderer_new(0, 0);
+        let renderer = hoedown_html_renderer_new(html_flags, 0);
         let mut opaque = MyOpaque {
             dfltblk: (*renderer).blockcode.unwrap(),
             toc_builder: if print_toc {Some(TocBuilder::new())} else {None}
@@ -553,14 +560,23 @@ impl<'a> fmt::Display for Markdown<'a> {
         let Markdown(md) = *self;
         // This is actually common enough to special-case
         if md.is_empty() { return Ok(()) }
-        render(fmt, md, false)
+        render(fmt, md, false, 0)
     }
 }
 
 impl<'a> fmt::Display for MarkdownWithToc<'a> {
     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
         let MarkdownWithToc(md) = *self;
-        render(fmt, md, true)
+        render(fmt, md, true, 0)
+    }
+}
+
+impl<'a> fmt::Display for MarkdownHtml<'a> {
+    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
+        let MarkdownHtml(md) = *self;
+        // This is actually common enough to special-case
+        if md.is_empty() { return Ok(()) }
+        render(fmt, md, false, HOEDOWN_HTML_ESCAPE)
     }
 }
 
@@ -613,7 +629,7 @@ pub fn plain_summary_line(md: &str) -> String {
 
 #[cfg(test)]
 mod tests {
-    use super::{LangString, Markdown};
+    use super::{LangString, Markdown, MarkdownHtml};
     use super::plain_summary_line;
     use html::render::reset_ids;
 
@@ -719,4 +735,15 @@ mod tests {
         t("# top header", "top header");
         t("## header", "header");
     }
+
+    #[test]
+    fn test_markdown_html_escape() {
+        fn t(input: &str, expect: &str) {
+            let output = format!("{}", MarkdownHtml(input));
+            assert_eq!(output, expect);
+        }
+
+        t("`Struct<'a, T>`", "<p><code>Struct&lt;&#39;a, T&gt;</code></p>\n");
+        t("Struct<'a, T>", "<p>Struct&lt;&#39;a, T&gt;</p>\n");
+    }
 }

src/librustdoc/html/render.rs

@@ -71,7 +71,7 @@ use html::format::{TyParamBounds, WhereClause, href, AbiSpace};
 use html::format::{VisSpace, Method, UnsafetySpace, MutableSpace};
 use html::format::fmt_impl_for_trait_page;
 use html::item_type::ItemType;
-use html::markdown::{self, Markdown};
+use html::markdown::{self, Markdown, MarkdownHtml};
 use html::{highlight, layout};
 
 /// A pair of name and its optional document.
@@ -1866,7 +1866,7 @@ fn short_stability(item: &clean::Item, cx: &Context, show_reason: bool) -> Vec<S
             } else {
                 String::new()
             };
-            let text = format!("Deprecated{}{}", since, Markdown(&deprecated_reason));
+            let text = format!("Deprecated{}{}", since, MarkdownHtml(&deprecated_reason));
             stability.push(format!("<div class='stab deprecated'>{}</div>", text))
         };
 
@@ -1891,7 +1891,7 @@ fn short_stability(item: &clean::Item, cx: &Context, show_reason: bool) -> Vec<S
             } else {
                 String::new()
             };
-            let text = format!("Unstable{}{}", unstable_extra, Markdown(&unstable_reason));
+            let text = format!("Unstable{}{}", unstable_extra, MarkdownHtml(&unstable_reason));
             stability.push(format!("<div class='stab unstable'>{}</div>", text))
         };
     } else if let Some(depr) = item.deprecation.as_ref() {
@@ -1906,7 +1906,7 @@ fn short_stability(item: &clean::Item, cx: &Context, show_reason: bool) -> Vec<S
             String::new()
         };
 
-        let text = format!("Deprecated{}{}", since, Markdown(&note));
+        let text = format!("Deprecated{}{}", since, MarkdownHtml(&note));
         stability.push(format!("<div class='stab deprecated'>{}</div>", text))
     }