auto merge of #9475 : alexcrichton/rust/rustdoc++, r=cmr

The commit messages are a good technical summary, a good visual summary (contrib is this version):

Pub use statements now rendered. Notice how almost all components are also clickable!
* http://static.rust-lang.org/doc/master/std/prelude/index.html
* http://www.contrib.andrew.cmu.edu/~acrichto/doc/std/prelude/index.html

Private things hidden by default (for at least some approximation of privacy). I hope to improve this once privacy is totally ironed out.
* http://static.rust-lang.org/doc/master/std/hashmap/struct.HashMap.html
* http://www.contrib.andrew.cmu.edu/~acrichto/doc/std/hashmap/struct.HashMap.html

Unindentation now works properly:
* http://static.rust-lang.org/doc/master/extra/getopts/index.html
* http://www.contrib.andrew.cmu.edu/~acrichto/doc/extra/getopts/index.html

Also sundown has massively reduced compilation time (of docs, not the of the crates)

3 files changed, 64 insertions, 39 deletions

diff --git a/src/libsyntax/ext/deriving/generic.rs b/src/libsyntax/ext/deriving/generic.rs
index 9222d8160ee..646b65d080b 100644
--- a/src/libsyntax/ext/deriving/generic.rs
+++ b/src/libsyntax/ext/deriving/generic.rs
@@ -59,7 +59,7 @@ associated with. It is only not `None` when the associated field has
 an identifier in the source code. For example, the `x`s in the
 following snippet
 
-~~~
+ ```
 struct A { x : int }
 
 struct B(int);
@@ -82,7 +82,7 @@ represented as a count of 0.
 
 The following simplified `Eq` is used for in-code examples:
 
-~~~
+ ```
 trait Eq {
     fn eq(&self, other: &Self);
 }
@@ -91,7 +91,7 @@ impl Eq for int {
         *self == *other
     }
 }
-~~~
+ ```
 
 Some examples of the values of `SubstructureFields` follow, using the
 above `Eq`, `A`, `B` and `C`.
@@ -100,50 +100,50 @@ above `Eq`, `A`, `B` and `C`.
 
 When generating the `expr` for the `A` impl, the `SubstructureFields` is
 
-~~~
+ ```
 Struct(~[(Some(<ident of x>),
          <expr for &self.x>,
          ~[<expr for &other.x])])
-~~~
+ ```
 
 For the `B` impl, called with `B(a)` and `B(b)`,
 
-~~~
+ ```
 Struct(~[(None,
           <expr for &a>
           ~[<expr for &b>])])
-~~~
+ ```
 
 ## Enums
 
 When generating the `expr` for a call with `self == C0(a)` and `other
 == C0(b)`, the SubstructureFields is
 
-~~~
+ ```
 EnumMatching(0, <ast::variant for C0>,
              ~[None,
                <expr for &a>,
                ~[<expr for &b>]])
-~~~
+ ```
 
 For `C1 {x}` and `C1 {x}`,
 
-~~~
+ ```
 EnumMatching(1, <ast::variant for C1>,
              ~[Some(<ident of x>),
                <expr for &self.x>,
                ~[<expr for &other.x>]])
-~~~
+ ```
 
 For `C0(a)` and `C1 {x}` ,
 
-~~~
+ ```
 EnumNonMatching(~[(0, <ast::variant for B0>,
                    ~[(None, <expr for &a>)]),
                   (1, <ast::variant for B1>,
                    ~[(Some(<ident of x>),
                       <expr for &other.x>)])])
-~~~
+ ```
 
 (and vice versa, but with the order of the outermost list flipped.)
 
@@ -158,7 +158,7 @@ StaticStruct(<ast::struct_def of B>, Left(1))
 
 StaticEnum(<ast::enum_def of C>, ~[(<ident of C0>, Left(1)),
                                    (<ident of C1>, Right(~[<ident of x>]))])
-~~~
+ ```
 
 */
 
@@ -547,7 +547,7 @@ impl<'self> MethodDef<'self> {
     }
 
     /**
-    ~~~
+    ```
     #[deriving(Eq)]
     struct A { x: int, y: int }
 
@@ -565,7 +565,7 @@ impl<'self> MethodDef<'self> {
             }
         }
     }
-    ~~~
+    ```
     */
     fn expand_struct_method_body(&self,
                                  cx: @ExtCtxt,
@@ -638,7 +638,7 @@ impl<'self> MethodDef<'self> {
     }
 
     /**
-    ~~~
+    ```
     #[deriving(Eq)]
     enum A {
         A1
@@ -661,7 +661,7 @@ impl<'self> MethodDef<'self> {
             }
         }
     }
-    ~~~
+    ```
     */
     fn expand_enum_method_body(&self,
                                cx: @ExtCtxt,
@@ -681,13 +681,13 @@ impl<'self> MethodDef<'self> {
     /**
     Creates the nested matches for an enum definition recursively, i.e.
 
-    ~~~
+    ```
     match self {
        Variant1 => match other { Variant1 => matching, Variant2 => nonmatching, ... },
        Variant2 => match other { Variant1 => nonmatching, Variant2 => matching, ... },
        ...
     }
-    ~~~
+    ```
 
     It acts in the most naive way, so every branch (and subbranch,
     subsubbranch, etc) exists, not just the ones where all the variants in
@@ -1058,10 +1058,10 @@ pub fn cs_fold(use_foldl: bool,
 Call the method that is being derived on all the fields, and then
 process the collected results. i.e.
 
-~~~
+ ```
 f(cx, span, ~[self_1.method(__arg_1_1, __arg_2_1),
               self_2.method(__arg_1_2, __arg_2_2)])
-~~~
+ ```
 */
 #[inline]
 pub fn cs_same_method(f: &fn(@ExtCtxt, Span, ~[@Expr]) -> @Expr,
diff --git a/src/libsyntax/ext/expand.rs b/src/libsyntax/ext/expand.rs
index 64f30803ca7..61c9ea7be14 100644
--- a/src/libsyntax/ext/expand.rs
+++ b/src/libsyntax/ext/expand.rs
@@ -944,7 +944,7 @@ pub fn std_macros() -> @str {
 
     # Example
 
-    ~~~ {.rust}
+    ```rust
     fn choose_weighted_item(v: &[Item]) -> Item {
         assert!(!v.is_empty());
         let mut so_far = 0u;
@@ -958,7 +958,7 @@ pub fn std_macros() -> @str {
         // type checker that it isn't possible to get down here
         unreachable!();
     }
-    ~~~
+    ```
 
     */
     macro_rules! unreachable (() => (
diff --git a/src/libsyntax/parse/comments.rs b/src/libsyntax/parse/comments.rs
index f13bd6d9123..88c9fc3e0f7 100644
--- a/src/libsyntax/parse/comments.rs
+++ b/src/libsyntax/parse/comments.rs
@@ -59,11 +59,19 @@ pub fn strip_doc_comment_decoration(comment: &str) -> ~str {
     fn vertical_trim(lines: ~[~str]) -> ~[~str] {
         let mut i = 0u;
         let mut j = lines.len();
+        // first line of all-stars should be omitted
+        if lines.len() > 0 && lines[0].iter().all(|c| c == '*') {
+            i += 1;
+        }
         while i < j && lines[i].trim().is_empty() {
-            i += 1u;
+            i += 1;
+        }
+        // like the first, a last line of all stars should be omitted
+        if j > i && lines[j - 1].iter().skip(1).all(|c| c == '*') {
+            j -= 1;
         }
-        while j > i && lines[j - 1u].trim().is_empty() {
-            j -= 1u;
+        while j > i && lines[j - 1].trim().is_empty() {
+            j -= 1;
         }
         return lines.slice(i, j).to_owned();
     }
@@ -106,8 +114,12 @@ pub fn strip_doc_comment_decoration(comment: &str) -> ~str {
         }
     }
 
-    if comment.starts_with("//") {
-        return comment.slice(3u, comment.len()).to_owned();
+    // one-line comments lose their prefix
+    static ONLINERS: &'static [&'static str] = &["///!", "///", "//!", "//"];
+    for prefix in ONLINERS.iter() {
+        if comment.starts_with(*prefix) {
+            return comment.slice_from(prefix.len()).to_owned();
+        }
     }
 
     if comment.starts_with("/*") {
@@ -384,29 +396,42 @@ mod test {
 
     #[test] fn test_block_doc_comment_1() {
         let comment = "/**\n * Test \n **  Test\n *   Test\n*/";
-        let correct_stripped = " Test \n*  Test\n   Test";
         let stripped = strip_doc_comment_decoration(comment);
-        assert_eq!(stripped.slice(0, stripped.len()), correct_stripped);
+        assert_eq!(stripped, ~" Test \n*  Test\n   Test");
     }
 
     #[test] fn test_block_doc_comment_2() {
         let comment = "/**\n * Test\n *  Test\n*/";
-        let correct_stripped = " Test\n  Test";
         let stripped = strip_doc_comment_decoration(comment);
-        assert_eq!(stripped.slice(0, stripped.len()), correct_stripped);
+        assert_eq!(stripped, ~" Test\n  Test");
     }
 
     #[test] fn test_block_doc_comment_3() {
         let comment = "/**\n let a: *int;\n *a = 5;\n*/";
-        let correct_stripped = " let a: *int;\n *a = 5;";
         let stripped = strip_doc_comment_decoration(comment);
-        assert_eq!(stripped.slice(0, stripped.len()), correct_stripped);
+        assert_eq!(stripped, ~" let a: *int;\n *a = 5;");
     }
 
-    #[test] fn test_line_doc_comment() {
-        let comment = "/// Test";
-        let correct_stripped = " Test";
+    #[test] fn test_block_doc_comment_4() {
+        let comment = "/*******************\n test\n *********************/";
         let stripped = strip_doc_comment_decoration(comment);
-        assert_eq!(stripped.slice(0, stripped.len()), correct_stripped);
+        assert_eq!(stripped, ~" test");
+    }
+
+    #[test] fn test_line_doc_comment() {
+        let stripped = strip_doc_comment_decoration("/// test");
+        assert_eq!(stripped, ~" test");
+        let stripped = strip_doc_comment_decoration("///! test");
+        assert_eq!(stripped, ~" test");
+        let stripped = strip_doc_comment_decoration("// test");
+        assert_eq!(stripped, ~" test");
+        let stripped = strip_doc_comment_decoration("// test");
+        assert_eq!(stripped, ~" test");
+        let stripped = strip_doc_comment_decoration("///test");
+        assert_eq!(stripped, ~"test");
+        let stripped = strip_doc_comment_decoration("///!test");
+        assert_eq!(stripped, ~"test");
+        let stripped = strip_doc_comment_decoration("//test");
+        assert_eq!(stripped, ~"test");
     }
 }