From 4fc5b822e218301eedf49ec249fdd1a0adf8ebd6 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Fri, 9 Mar 2012 17:40:40 -0800 Subject: [PATCH] rustdoc: Simplify the relation between the brief and long description Brief is just used for indexes now --- src/rustdoc/desc_to_brief_pass.rs | 129 +++++------------------------- src/rustdoc/markdown_pass.rs | 87 ++++---------------- 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, - desc: option -) -> (option, option) { - - if option::is_some(brief) || option::is_none(desc) { - ret (brief, desc); +fn extract(desc: option) -> option { + if option::is_none(desc) { + ret none } parse_desc(option::get(desc)) } -fn parse_desc(desc: str) -> (option, option) { +fn parse_desc(desc: str) -> option { const max_brief_len: uint = 120u; @@ -179,18 +113,12 @@ fn parse_desc(desc: str) -> (option, option) { 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, desc: option, sections: [doc::section] ) { - write_brief(ctxt, brief); write_desc(ctxt, desc); write_sections(ctxt, sections); } -fn write_brief( - ctxt: ctxt, - brief: option -) { - 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 @@ -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)); } @@ -340,12 +311,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\"];"); @@ -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, - brief: option, desc: option, 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) { @@ -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 ); @@ -652,13 +614,6 @@ fn should_write_iface_header() { assert str::contains(markdown, "## Interface `i`"); } -#[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( @@ -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); } @@ -698,13 +653,6 @@ fn should_write_impl_header_with_iface() { assert str::contains(markdown, "## Implementation `i of j for int`"); } -#[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( @@ -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] @@ -741,13 +689,6 @@ fn should_write_type_header() { assert str::contains(markdown, "## Type `t`"); } -#[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(