rustdoc: Simplify the relation between the brief and long description

Brief is just used for indexes now

2 files changed, 32 insertions, 184 deletions

diff --git a/src/rustdoc/desc_to_brief_pass.rs b/src/rustdoc/desc_to_brief_pass.rs
index 695742cbebc..429f0c0a05a 100644
--- a/src/rustdoc/desc_to_brief_pass.rs
+++ b/src/rustdoc/desc_to_brief_pass.rs
@@ -31,11 +31,9 @@ fn run(
 
 fn fold_item(fold: fold::fold<()>, doc: doc::itemdoc) -> doc::itemdoc {
     let doc = fold::default_seq_fold_item(fold, doc);
-    let (brief, desc) = modify(doc.brief, doc.desc);
 
     {
-        brief: brief,
-        desc: desc
+        brief: extract(doc.desc)
         with doc
     }
 }
@@ -45,11 +43,8 @@ fn fold_iface(fold: fold::fold<()>, doc: doc::ifacedoc) -> doc::ifacedoc {
 
     {
         methods: par::anymap(doc.methods) {|doc|
-            let (brief, desc) = modify(doc.brief, doc.desc);
-
             {
-                brief: brief,
-                desc: desc
+                brief: extract(doc.desc)
                 with doc
             }
         }
@@ -62,11 +57,8 @@ fn fold_impl(fold: fold::fold<()>, doc: doc::impldoc) -> doc::impldoc {
 
     {
         methods: par::anymap(doc.methods) {|doc|
-            let (brief, desc) = modify(doc.brief, doc.desc);
-
             {
-                brief: brief,
-                desc: desc
+                brief: extract(doc.desc)
                 with doc
             }
         }
@@ -75,76 +67,22 @@ fn fold_impl(fold: fold::fold<()>, doc: doc::impldoc) -> doc::impldoc {
 }
 
 #[test]
-fn should_promote_mod_desc() {
-    let doc = test::mk_doc("#[doc(desc = \"desc\")] mod m { }");
+fn should_promote_desc() {
+    let doc = test::mk_doc("#[doc = \"desc\"] mod m { }");
     assert doc.cratemod().mods()[0].brief() == some("desc");
-    assert doc.cratemod().mods()[0].desc() == none;
-}
-
-#[test]
-fn should_promote_const_desc() {
-    let doc = test::mk_doc("#[doc(desc = \"desc\")] const a: bool = true;");
-    assert doc.cratemod().consts()[0].brief() == some("desc");
-    assert doc.cratemod().consts()[0].desc() == none;
-}
-
-#[test]
-fn should_promote_fn_desc() {
-    let doc = test::mk_doc("#[doc(desc = \"desc\")] fn a() { }");
-    assert doc.cratemod().fns()[0].brief() == some("desc");
-    assert doc.cratemod().fns()[0].desc() == none;
-}
-
-#[test]
-fn should_promote_enum_desc() {
-    let doc = test::mk_doc("#[doc(desc = \"desc\")] enum a { b }");
-    assert doc.cratemod().enums()[0].brief() == some("desc");
-    assert doc.cratemod().enums()[0].desc() == none;
-}
-
-#[test]
-fn should_promote_resource_desc() {
-    let doc = test::mk_doc(
-        "#[doc(desc = \"desc\")] resource r(a: bool) { }");
-    assert doc.cratemod().resources()[0].brief() == some("desc");
-    assert doc.cratemod().resources()[0].desc() == none;
-}
-
-#[test]
-fn should_promote_iface_desc() {
-    let doc = test::mk_doc("#[doc(desc = \"desc\")] iface i { fn a(); }");
-    assert doc.cratemod().ifaces()[0].brief() == some("desc");
-    assert doc.cratemod().ifaces()[0].desc() == none;
 }
 
 #[test]
 fn should_promote_iface_method_desc() {
-    let doc = test::mk_doc("iface i { #[doc(desc = \"desc\")] fn a(); }");
+    let doc = test::mk_doc("iface i { #[doc = \"desc\"] fn a(); }");
     assert doc.cratemod().ifaces()[0].methods[0].brief == some("desc");
-    assert doc.cratemod().ifaces()[0].methods[0].desc == none;
-}
-
-#[test]
-fn should_promote_impl_desc() {
-    let doc = test::mk_doc(
-        "#[doc(desc = \"desc\")] impl i for int { fn a() { } }");
-    assert doc.cratemod().impls()[0].brief() == some("desc");
-    assert doc.cratemod().impls()[0].desc() == none;
 }
 
 #[test]
 fn should_promote_impl_method_desc() {
     let doc = test::mk_doc(
-        "impl i for int { #[doc(desc = \"desc\")] fn a() { } }");
+        "impl i for int { #[doc = \"desc\"] fn a() { } }");
     assert doc.cratemod().impls()[0].methods[0].brief == some("desc");
-    assert doc.cratemod().impls()[0].methods[0].desc == none;
-}
-
-#[test]
-fn should_promote_type_desc() {
-    let doc = test::mk_doc("#[doc(desc = \"desc\")] type t = int;");
-    assert doc.cratemod().types()[0].brief() == some("desc");
-    assert doc.cratemod().types()[0].desc() == none;
 }
 
 #[cfg(test)]
@@ -158,19 +96,15 @@ mod test {
     }
 }
 
-fn modify(
-    brief: option<str>,
-    desc: option<str>
-) -> (option<str>, option<str>) {
-
-    if option::is_some(brief) || option::is_none(desc) {
-        ret (brief, desc);
+fn extract(desc: option<str>) -> option<str> {
+    if option::is_none(desc) {
+        ret none
     }
 
     parse_desc(option::get(desc))
 }
 
-fn parse_desc(desc: str) -> (option<str>, option<str>) {
+fn parse_desc(desc: str) -> option<str> {
 
     const max_brief_len: uint = 120u;
 
@@ -179,18 +113,12 @@ fn parse_desc(desc: str) -> (option<str>, option<str>) {
     if check vec::is_not_empty(paras) {
         let maybe_brief = vec::head(paras);
         if str::len(maybe_brief) <= max_brief_len {
-            let desc_paras = vec::tail(paras);
-            let desc = if vec::is_not_empty(desc_paras) {
-                some(str::connect(desc_paras, "\n\n"))
-            } else {
-                none
-            };
-            (some(maybe_brief), desc)
+            some(maybe_brief)
         } else {
-            (none, some(desc))
+            none
         }
     } else {
-        (none, none)
+        none
     }
 }
 
@@ -244,16 +172,13 @@ fn test_paragraphs_2() {
 
 #[test]
 fn should_promote_short_descs() {
-    let brief = none;
     let desc = some("desc");
-    let (newbrief, newdesc) = modify(brief, desc);
-    assert newbrief == desc;
-    assert newdesc == none;
+    let brief = extract(desc);
+    assert brief == desc;
 }
 
 #[test]
 fn should_not_promote_long_descs() {
-    let brief = none;
     let desc = some("Warkworth Castle is a ruined medieval building
 in the town of the same name in the English county of Northumberland.
 The town and castle occupy a loop of the River Coquet, less than a mile
@@ -262,24 +187,6 @@ but traditionally its construction has been ascribed to Prince Henry of
 Scotland in the mid 12th century, although it may have been built by
 King Henry II of England when he took control of England'snorthern
 counties.");
-    let (newbrief, _) = modify(brief, desc);
-    assert newbrief == none;
-}
-
-#[test]
-fn should_not_promote_descs_over_brief() {
-    let brief = some("brief");
-    let desc = some("desc");
-    let (newbrief, newdesc) = modify(brief, desc);
-    assert newbrief == brief;
-    assert newdesc == desc;
-}
-
-#[test]
-fn should_extract_brief_from_desc() {
-    let brief = none;
-    let desc = some("brief\n\ndesc");
-    let (newbrief, newdesc) = modify(brief, desc);
-    assert newbrief == some("brief");
-    assert newdesc == some("desc");
+    let brief = extract(desc);
+    assert brief == none;
 }
diff --git a/src/rustdoc/markdown_pass.rs b/src/rustdoc/markdown_pass.rs
index 3cc403b2ace..41fd2794f43 100644
--- a/src/rustdoc/markdown_pass.rs
+++ b/src/rustdoc/markdown_pass.rs
@@ -241,42 +241,13 @@ fn should_write_full_path_to_mod() {
 
 fn write_common(
     ctxt: ctxt,
-    brief: option<str>,
     desc: option<str>,
     sections: [doc::section]
 ) {
-    write_brief(ctxt, brief);
     write_desc(ctxt, desc);
     write_sections(ctxt, sections);
 }
 
-fn write_brief(
-    ctxt: ctxt,
-    brief: option<str>
-) {
-    alt brief {
-      some(brief) {
-        ctxt.w.write_line(brief);
-        ctxt.w.write_line("");
-      }
-      none { }
-    }
-}
-
-#[test]
-fn should_leave_blank_line_after_brief() {
-    let markdown = test::render("#[doc(brief = \"brief\")] fn a() { }");
-    assert str::contains(markdown, "brief\n\n");
-}
-
-#[test]
-fn should_leave_blank_line_between_brief_and_desc() {
-    let markdown = test::render(
-        "#[doc(brief = \"brief\", desc = \"desc\")] fn a() { }"
-    );
-    assert str::contains(markdown, "brief\n\ndesc");
-}
-
 fn write_desc(
     ctxt: ctxt,
     desc: option<str>
@@ -316,7 +287,7 @@ fn write_mod_contents(
     ctxt: ctxt,
     doc: doc::moddoc
 ) {
-    write_common(ctxt, doc.brief(), doc.desc(), doc.sections());
+    write_common(ctxt, doc.desc(), doc.sections());
     if option::is_some(doc.index) {
         write_index(ctxt, option::get(doc.index));
     }
@@ -341,12 +312,6 @@ fn write_item(ctxt: ctxt, doc: doc::itemtag) {
 }
 
 #[test]
-fn should_write_crate_brief_description() {
-    let markdown = test::render("#[doc(brief = \"this is the crate\")];");
-    assert str::contains(markdown, "this is the crate");
-}
-
-#[test]
 fn should_write_crate_description() {
     let markdown = test::render("#[doc = \"this is the crate\"];");
     assert str::contains(markdown, "this is the crate");
@@ -394,7 +359,7 @@ fn should_not_write_index_if_no_entries() {
 
 fn write_nmod(ctxt: ctxt, doc: doc::nmoddoc) {
     write_header(ctxt, h1, doc::nmodtag(doc));
-    write_common(ctxt, doc.brief(), doc.desc(), doc.sections());
+    write_common(ctxt, doc.desc(), doc.sections());
 
     for fndoc in doc.fns {
         write_fn(ctxt, fndoc);
@@ -422,7 +387,6 @@ fn write_fn(
     write_fnlike(
         ctxt,
         doc.sig,
-        doc.brief(),
         doc.desc(),
         doc.sections()
     );
@@ -431,12 +395,11 @@ fn write_fn(
 fn write_fnlike(
     ctxt: ctxt,
     sig: option<str>,
-    brief: option<str>,
     desc: option<str>,
     sections: [doc::section]
 ) {
     write_sig(ctxt, sig);
-    write_common(ctxt, brief, desc, sections);
+    write_common(ctxt, desc, sections);
 }
 
 fn write_sig(ctxt: ctxt, sig: option<str>) {
@@ -496,7 +459,7 @@ fn should_correctly_indent_fn_signature() {
 
 #[test]
 fn should_leave_blank_line_between_fn_header_and_sig() {
-    let markdown = test::render("#[doc(brief = \"brief\")] fn a() { }");
+    let markdown = test::render("fn a() { }");
     assert str::contains(markdown, "Function `a`\n\n    fn a()");
 }
 
@@ -506,7 +469,7 @@ fn write_const(
 ) {
     write_header(ctxt, h2, doc::consttag(doc));
     write_sig(ctxt, doc.sig);
-    write_common(ctxt, doc.brief(), doc.desc(), doc.sections());
+    write_common(ctxt, doc.desc(), doc.sections());
 }
 
 #[test]
@@ -518,9 +481,9 @@ fn should_write_const_header() {
 #[test]
 fn should_write_const_description() {
     let markdown = test::render(
-        "#[doc(brief = \"a\", desc = \"b\")]\
+        "#[doc = \"b\"]\
          const a: bool = true;");
-    assert str::contains(markdown, "\n\na\n\nb\n\n");
+    assert str::contains(markdown, "\n\nb\n\n");
 }
 
 fn write_enum(
@@ -528,7 +491,7 @@ fn write_enum(
     doc: doc::enumdoc
 ) {
     write_header(ctxt, h2, doc::enumtag(doc));
-    write_common(ctxt, doc.brief(), doc.desc(), doc.sections());
+    write_common(ctxt, doc.desc(), doc.sections());
     write_variants(ctxt, doc.variants);
 }
 
@@ -541,8 +504,8 @@ fn should_write_enum_header() {
 #[test]
 fn should_write_enum_description() {
     let markdown = test::render(
-        "#[doc(brief = \"a\", desc = \"b\")] enum a { b }");
-    assert str::contains(markdown, "\n\na\n\nb\n\n");
+        "#[doc = \"b\"] enum a { b }");
+    assert str::contains(markdown, "\n\nb\n\n");
 }
 
 fn write_variants(
@@ -610,7 +573,7 @@ fn should_write_variant_list_with_signatures() {
 fn write_res(ctxt: ctxt, doc: doc::resdoc) {
     write_header(ctxt, h2, doc::restag(doc));
     write_sig(ctxt, doc.sig);
-    write_common(ctxt, doc.brief(), doc.desc(), doc.sections());
+    write_common(ctxt, doc.desc(), doc.sections());
 }
 
 #[test]
@@ -627,7 +590,7 @@ fn should_write_resource_signature() {
 
 fn write_iface(ctxt: ctxt, doc: doc::ifacedoc) {
     write_header(ctxt, h2, doc::ifacetag(doc));
-    write_common(ctxt, doc.brief(), doc.desc(), doc.sections());
+    write_common(ctxt, doc.desc(), doc.sections());
     write_methods(ctxt, doc.methods);
 }
 
@@ -640,7 +603,6 @@ fn write_method(ctxt: ctxt, doc: doc::methoddoc) {
     write_fnlike(
         ctxt,
         doc.sig,
-        doc.brief,
         doc.desc,
         doc.sections
     );
@@ -653,13 +615,6 @@ fn should_write_iface_header() {
 }
 
 #[test]
-fn should_write_iface_brief() {
-    let markdown = test::render(
-        "#[doc(brief = \"brief\")] iface i { fn a(); }");
-    assert str::contains(markdown, "brief");
-}
-
-#[test]
 fn should_write_iface_desc() {
     let markdown = test::render(
         "#[doc(desc = \"desc\")] iface i { fn a(); }");
@@ -682,7 +637,7 @@ fn should_write_iface_method_signature() {
 
 fn write_impl(ctxt: ctxt, doc: doc::impldoc) {
     write_header(ctxt, h2, doc::impltag(doc));
-    write_common(ctxt, doc.brief(), doc.desc(), doc.sections());
+    write_common(ctxt, doc.desc(), doc.sections());
     write_methods(ctxt, doc.methods);
 }
 
@@ -699,13 +654,6 @@ fn should_write_impl_header_with_iface() {
 }
 
 #[test]
-fn should_write_impl_brief() {
-    let markdown = test::render(
-        "#[doc(brief = \"brief\")] impl i for int { fn a() { } }");
-    assert str::contains(markdown, "brief");
-}
-
-#[test]
 fn should_write_impl_desc() {
     let markdown = test::render(
         "#[doc(desc = \"desc\")] impl i for int { fn a() { } }");
@@ -732,7 +680,7 @@ fn write_type(
 ) {
     write_header(ctxt, h2, doc::tytag(doc));
     write_sig(ctxt, doc.sig);
-    write_common(ctxt, doc.brief(), doc.desc(), doc.sections());
+    write_common(ctxt, doc.desc(), doc.sections());
 }
 
 #[test]
@@ -742,13 +690,6 @@ fn should_write_type_header() {
 }
 
 #[test]
-fn should_write_type_brief() {
-    let markdown = test::render(
-        "#[doc(brief = \"brief\")] type t = int;");
-    assert str::contains(markdown, "\n\nbrief\n\n");
-}
-
-#[test]
 fn should_write_type_desc() {
     let markdown = test::render(
         "#[doc(desc = \"desc\")] type t = int;");