squiid/rust
1
0
Fork 0
Code Issues Pull requests Projects Activity

rustdoc: Simplify the relation between the brief and long description

Browse source 
Brief is just used for indexes now
This commit is contained in:
Brian Anderson 2012-03-09 17:40:40 -08:00
parent e8c7b5347d
commit 4fc5b822e2
2 changed files with 32 additions and 184 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

129
src/rustdoc/desc_to_brief_pass.rs
View file

@ -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;
}

87
src/rustdoc/markdown_pass.rs
View file

@ -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));
}
@ -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<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
);
@ -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(