auto merge of rust-lang#6700 : ben0x539/rust/nestvariantdocs, r=thest…

…inger

This indents all but the first line of multi-line annotations for individual enum variants with four spaces so that pandoc will recognize everything as belonging to the same list item.

Since that introduces `<p>` tags for some list items, I've gone ahead and inserted blank lines after each list item so that consistently get `<p>` tags for all `<li>`s documenting variants. It's a bit less compact now but still tolerable, I think.

src/librustdoc/markdown_pass.rs

@@ -451,16 +451,32 @@ fn write_variants(
 fn write_variant(ctxt: &Ctxt, doc: doc::VariantDoc) {
     assert!(doc.sig.is_some());
     let sig = (&doc.sig).get();
+
+    // space out list items so they all end up within paragraph elements
+    ctxt.w.put_line(~"");
+
     match copy doc.desc {
         Some(desc) => {
-            ctxt.w.put_line(fmt!("* `%s` - %s", sig, desc));
+            ctxt.w.put_line(list_item_indent(fmt!("* `%s` - %s", sig, desc)));
         }
         None => {
             ctxt.w.put_line(fmt!("* `%s`", sig));
         }
     }
 }
 
+fn list_item_indent(item: &str) -> ~str {
+    let mut indented = ~[];
+    for str::each_line_any(item) |line| {
+        indented.push(line);
+    }
+
+    // separate markdown elements within `*` lists must be indented by four
+    // spaces, or they will escape the list context. indenting everything
+    // seems fine though.
+    str::connect_slices(indented, "\n    ")
+}
+
 fn write_trait(ctxt: &Ctxt, doc: doc::TraitDoc) {
     write_common(ctxt, doc.desc(), doc.sections());
     write_methods(ctxt, doc.methods);
@@ -807,7 +823,9 @@ mod test {
         assert!(str::contains(
             markdown,
             "\n\n#### Variants\n\
+             \n\
              \n* `b` - test\
+             \n\
              \n* `c` - test\n\n"));
     }
 
@@ -817,7 +835,24 @@ mod test {
         assert!(str::contains(
             markdown,
             "\n\n#### Variants\n\
+             \n\
              \n* `b`\
+             \n\
+             \n* `c`\n\n"));
+    }
+
+    #[test]
+    fn should_write_variant_list_with_indent() {
+        let markdown = render(
+            ~"enum a { #[doc = \"line 1\\n\\nline 2\"] b, c }");
+        assert!(str::contains(
+            markdown,
+            "\n\n#### Variants\n\
+             \n\
+             \n* `b` - line 1\
+             \n    \
+             \n    line 2\
+             \n\
              \n* `c`\n\n"));
     }
 
@@ -827,7 +862,9 @@ mod test {
         assert!(str::contains(
             markdown,
             "\n\n#### Variants\n\
+             \n\
              \n* `b(int)`\
+             \n\
              \n* `c(int)` - a\n\n"));
     }