rustdoc: Write sections in markdown
This commit is contained in:
parent
0ad8265fee
commit
e399263b5e
1 changed files with 93 additions and 60 deletions
|
@ -120,7 +120,8 @@ fn should_request_new_writer_for_each_page() {
|
||||||
enum hlvl {
|
enum hlvl {
|
||||||
h1 = 1,
|
h1 = 1,
|
||||||
h2 = 2,
|
h2 = 2,
|
||||||
h3 = 3
|
h3 = 3,
|
||||||
|
h4 = 4
|
||||||
}
|
}
|
||||||
|
|
||||||
fn write_header(ctxt: ctxt, lvl: hlvl, doc: doc::itemtag) {
|
fn write_header(ctxt: ctxt, lvl: hlvl, doc: doc::itemtag) {
|
||||||
|
@ -238,12 +239,84 @@ fn should_write_full_path_to_mod() {
|
||||||
assert str::contains(markdown, "# Module `a::b::c`");
|
assert str::contains(markdown, "# Module `a::b::c`");
|
||||||
}
|
}
|
||||||
|
|
||||||
|
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>
|
||||||
|
) {
|
||||||
|
alt desc {
|
||||||
|
some(desc) {
|
||||||
|
ctxt.w.write_line(desc);
|
||||||
|
ctxt.w.write_line("");
|
||||||
|
}
|
||||||
|
none { }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
fn write_sections(ctxt: ctxt, sections: [doc::section]) {
|
||||||
|
vec::iter(sections) {|section|
|
||||||
|
write_section(ctxt, section);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
fn write_section(ctxt: ctxt, section: doc::section) {
|
||||||
|
write_header_(ctxt, h4, section.header);
|
||||||
|
ctxt.w.write_line(section.body);
|
||||||
|
ctxt.w.write_line("");
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn should_write_sections() {
|
||||||
|
let markdown = test::render(
|
||||||
|
"#[doc = \"\
|
||||||
|
# Header\n\
|
||||||
|
Body\"]\
|
||||||
|
mod a { }");
|
||||||
|
assert str::contains(markdown, "#### Header\n\nBody\n\n");
|
||||||
|
}
|
||||||
|
|
||||||
fn write_mod_contents(
|
fn write_mod_contents(
|
||||||
ctxt: ctxt,
|
ctxt: ctxt,
|
||||||
doc: doc::moddoc
|
doc: doc::moddoc
|
||||||
) {
|
) {
|
||||||
write_brief(ctxt, doc.brief());
|
write_common(ctxt, doc.brief(), doc.desc(), doc.sections());
|
||||||
write_desc(ctxt, doc.desc());
|
|
||||||
if option::is_some(doc.index) {
|
if option::is_some(doc.index) {
|
||||||
write_index(ctxt, option::get(doc.index));
|
write_index(ctxt, option::get(doc.index));
|
||||||
}
|
}
|
||||||
|
@ -321,9 +394,7 @@ fn should_not_write_index_if_no_entries() {
|
||||||
|
|
||||||
fn write_nmod(ctxt: ctxt, doc: doc::nmoddoc) {
|
fn write_nmod(ctxt: ctxt, doc: doc::nmoddoc) {
|
||||||
write_header(ctxt, h1, doc::nmodtag(doc));
|
write_header(ctxt, h1, doc::nmodtag(doc));
|
||||||
|
write_common(ctxt, doc.brief(), doc.desc(), doc.sections());
|
||||||
write_brief(ctxt, doc.brief());
|
|
||||||
write_desc(ctxt, doc.desc());
|
|
||||||
|
|
||||||
for fndoc in doc.fns {
|
for fndoc in doc.fns {
|
||||||
write_fn(ctxt, fndoc);
|
write_fn(ctxt, fndoc);
|
||||||
|
@ -353,6 +424,7 @@ fn write_fn(
|
||||||
doc.sig,
|
doc.sig,
|
||||||
doc.brief(),
|
doc.brief(),
|
||||||
doc.desc(),
|
doc.desc(),
|
||||||
|
doc.sections(),
|
||||||
doc.args,
|
doc.args,
|
||||||
doc.return,
|
doc.return,
|
||||||
doc.failure
|
doc.failure
|
||||||
|
@ -364,13 +436,13 @@ fn write_fnlike(
|
||||||
sig: option<str>,
|
sig: option<str>,
|
||||||
brief: option<str>,
|
brief: option<str>,
|
||||||
desc: option<str>,
|
desc: option<str>,
|
||||||
|
sections: [doc::section],
|
||||||
args: [doc::argdoc],
|
args: [doc::argdoc],
|
||||||
return: doc::retdoc,
|
return: doc::retdoc,
|
||||||
failure: option<str>
|
failure: option<str>
|
||||||
) {
|
) {
|
||||||
write_sig(ctxt, sig);
|
write_sig(ctxt, sig);
|
||||||
write_brief(ctxt, brief);
|
write_common(ctxt, brief, desc, sections);
|
||||||
write_desc(ctxt, desc);
|
|
||||||
write_args(ctxt, args);
|
write_args(ctxt, args);
|
||||||
write_return(ctxt, return);
|
write_return(ctxt, return);
|
||||||
write_failure(ctxt, failure);
|
write_failure(ctxt, failure);
|
||||||
|
@ -437,46 +509,6 @@ fn should_leave_blank_line_between_fn_header_and_sig() {
|
||||||
assert str::contains(markdown, "Function `a`\n\n fn a()");
|
assert str::contains(markdown, "Function `a`\n\n fn a()");
|
||||||
}
|
}
|
||||||
|
|
||||||
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>
|
|
||||||
) {
|
|
||||||
alt desc {
|
|
||||||
some(desc) {
|
|
||||||
ctxt.w.write_line(desc);
|
|
||||||
ctxt.w.write_line("");
|
|
||||||
}
|
|
||||||
none { }
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
fn write_args(
|
fn write_args(
|
||||||
ctxt: ctxt,
|
ctxt: ctxt,
|
||||||
args: [doc::argdoc]
|
args: [doc::argdoc]
|
||||||
|
@ -602,8 +634,7 @@ fn write_const(
|
||||||
) {
|
) {
|
||||||
write_header(ctxt, h2, doc::consttag(doc));
|
write_header(ctxt, h2, doc::consttag(doc));
|
||||||
write_sig(ctxt, doc.ty);
|
write_sig(ctxt, doc.ty);
|
||||||
write_brief(ctxt, doc.brief());
|
write_common(ctxt, doc.brief(), doc.desc(), doc.sections());
|
||||||
write_desc(ctxt, doc.desc());
|
|
||||||
}
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
|
@ -625,8 +656,7 @@ fn write_enum(
|
||||||
doc: doc::enumdoc
|
doc: doc::enumdoc
|
||||||
) {
|
) {
|
||||||
write_header(ctxt, h2, doc::enumtag(doc));
|
write_header(ctxt, h2, doc::enumtag(doc));
|
||||||
write_brief(ctxt, doc.brief());
|
write_common(ctxt, doc.brief(), doc.desc(), doc.sections());
|
||||||
write_desc(ctxt, doc.desc());
|
|
||||||
write_variants(ctxt, doc.variants);
|
write_variants(ctxt, doc.variants);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -708,8 +738,7 @@ fn should_write_variant_list_with_signatures() {
|
||||||
fn write_res(ctxt: ctxt, doc: doc::resdoc) {
|
fn write_res(ctxt: ctxt, doc: doc::resdoc) {
|
||||||
write_header(ctxt, h2, doc::restag(doc));
|
write_header(ctxt, h2, doc::restag(doc));
|
||||||
write_sig(ctxt, doc.sig);
|
write_sig(ctxt, doc.sig);
|
||||||
write_brief(ctxt, doc.brief());
|
write_common(ctxt, doc.brief(), doc.desc(), doc.sections());
|
||||||
write_desc(ctxt, doc.desc());
|
|
||||||
write_args(ctxt, doc.args);
|
write_args(ctxt, doc.args);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -734,8 +763,7 @@ fn should_write_resource_args() {
|
||||||
|
|
||||||
fn write_iface(ctxt: ctxt, doc: doc::ifacedoc) {
|
fn write_iface(ctxt: ctxt, doc: doc::ifacedoc) {
|
||||||
write_header(ctxt, h2, doc::ifacetag(doc));
|
write_header(ctxt, h2, doc::ifacetag(doc));
|
||||||
write_brief(ctxt, doc.brief());
|
write_common(ctxt, doc.brief(), doc.desc(), doc.sections());
|
||||||
write_desc(ctxt, doc.desc());
|
|
||||||
write_methods(ctxt, doc.methods);
|
write_methods(ctxt, doc.methods);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -750,6 +778,7 @@ fn write_method(ctxt: ctxt, doc: doc::methoddoc) {
|
||||||
doc.sig,
|
doc.sig,
|
||||||
doc.brief,
|
doc.brief,
|
||||||
doc.desc,
|
doc.desc,
|
||||||
|
doc.sections,
|
||||||
doc.args,
|
doc.args,
|
||||||
doc.return,
|
doc.return,
|
||||||
doc.failure
|
doc.failure
|
||||||
|
@ -827,8 +856,7 @@ fn should_write_iface_method_failure_conditions() {
|
||||||
|
|
||||||
fn write_impl(ctxt: ctxt, doc: doc::impldoc) {
|
fn write_impl(ctxt: ctxt, doc: doc::impldoc) {
|
||||||
write_header(ctxt, h2, doc::impltag(doc));
|
write_header(ctxt, h2, doc::impltag(doc));
|
||||||
write_brief(ctxt, doc.brief());
|
write_common(ctxt, doc.brief(), doc.desc(), doc.sections());
|
||||||
write_desc(ctxt, doc.desc());
|
|
||||||
write_methods(ctxt, doc.methods);
|
write_methods(ctxt, doc.methods);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -913,8 +941,7 @@ fn write_type(
|
||||||
) {
|
) {
|
||||||
write_header(ctxt, h2, doc::tytag(doc));
|
write_header(ctxt, h2, doc::tytag(doc));
|
||||||
write_sig(ctxt, doc.sig);
|
write_sig(ctxt, doc.sig);
|
||||||
write_brief(ctxt, doc.brief());
|
write_common(ctxt, doc.brief(), doc.desc(), doc.sections());
|
||||||
write_desc(ctxt, doc.desc());
|
|
||||||
}
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
|
@ -968,6 +995,12 @@ mod test {
|
||||||
#debug("doc (path): %?", doc);
|
#debug("doc (path): %?", doc);
|
||||||
let doc = attr_pass::mk_pass().f(srv, doc);
|
let doc = attr_pass::mk_pass().f(srv, doc);
|
||||||
#debug("doc (attr): %?", doc);
|
#debug("doc (attr): %?", doc);
|
||||||
|
let doc = unindent_pass::mk_pass().f(srv, doc);
|
||||||
|
#debug("doc (unindent): %?", doc);
|
||||||
|
let doc = sectionalize_pass::mk_pass().f(srv, doc);
|
||||||
|
#debug("doc (trim): %?", doc);
|
||||||
|
let doc = trim_pass::mk_pass().f(srv, doc);
|
||||||
|
#debug("doc (sectionalize): %?", doc);
|
||||||
let doc = markdown_index_pass::mk_pass(config).f(srv, doc);
|
let doc = markdown_index_pass::mk_pass(config).f(srv, doc);
|
||||||
#debug("doc (index): %?", doc);
|
#debug("doc (index): %?", doc);
|
||||||
(srv, doc)
|
(srv, doc)
|
||||||
|
|
Loading…
Reference in a new issue