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

rustdoc: Simplify attr pass

Browse source
This commit is contained in:
Brian Anderson 2012-02-17 16:52:27 -08:00
parent 22de9292c6
commit cec1679cf6
2 changed files with 100 additions and 308 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

229
src/rustdoc/attr_parser.rs
View file

@ -9,25 +9,21 @@ import rustc::syntax::ast;
import rustc::front::attr;
import core::tuple;
export crate_attrs, mod_attrs, fn_attrs, arg_attrs,
const_attrs, enum_attrs, variant_attrs, res_attrs,
iface_attrs, method_attrs, impl_attrs, type_attrs;
export parse_crate, parse_mod, parse_fn, parse_const,
parse_enum, parse_variant, parse_res,
parse_iface, parse_method, parse_impl, parse_type;
export crate_attrs, basic_attrs, fn_attrs, arg_attrs,
variant_attrs, res_attrs, method_attrs;
export parse_crate, parse_basic, parse_fn,
parse_variant, parse_res, parse_method;
type crate_attrs = {
name: option<str>
};
type mod_attrs = {
type basic_attrs = {
brief: option<str>,
desc: option<str>
};
type fn_attrs = {
brief: option<str>,
desc: option<str>,
args: [arg_attrs],
return: option<str>,
failure: option<str>
@ -38,43 +34,16 @@ type arg_attrs = {
desc: str
};
type const_attrs = {
brief: option<str>,
desc: option<str>
};
type enum_attrs = {
brief: option<str>,
desc: option<str>
};
type variant_attrs = {
desc: option<str>
};
type res_attrs = {
brief: option<str>,
desc: option<str>,
args: [arg_attrs]
};
type iface_attrs = {
brief: option<str>,
desc: option<str>
};
type impl_attrs = {
brief: option<str>,
desc: option<str>
};
type method_attrs = fn_attrs;
type type_attrs = {
brief: option<str>,
desc: option<str>
};
#[cfg(test)]
mod test {
@ -174,40 +143,36 @@ fn parse_basic(
)
}
fn parse_mod(attrs: [ast::attribute]) -> mod_attrs {
parse_basic(attrs)
}
#[test]
fn parse_mod_should_handle_undocumented_mods() {
fn parse_basic_should_handle_undocumented_mods() {
let source = "";
let attrs = test::parse_attributes(source);
let attrs = parse_mod(attrs);
let attrs = parse_basic(attrs);
assert attrs.brief == none;
assert attrs.desc == none;
}
#[test]
fn parse_mod_should_parse_simple_doc_attributes() {
fn parse_basic_should_parse_simple_doc_attributes() {
let source = "#[doc = \"basic\"]";
let attrs = test::parse_attributes(source);
let attrs = parse_mod(attrs);
let attrs = parse_basic(attrs);
assert attrs.desc == some("basic");
}
#[test]
fn parse_mod_should_parse_the_brief_description() {
fn parse_basic_should_parse_the_brief_description() {
let source = "#[doc(brief = \"short\")]";
let attrs = test::parse_attributes(source);
let attrs = parse_mod(attrs);
let attrs = parse_basic(attrs);
assert attrs.brief == some("short");
}
#[test]
fn parse_mod_should_parse_the_long_description() {
fn parse_basic_should_parse_the_long_description() {
let source = "#[doc(desc = \"description\")]";
let attrs = test::parse_attributes(source);
let attrs = parse_mod(attrs);
let attrs = parse_basic(attrs);
assert attrs.desc == some("description");
}
@ -246,37 +211,35 @@ fn parse_short_doc_or<T>(
}
}
fn parse_fn(
attrs: [ast::attribute]
) -> fn_attrs {
parse_short_doc_or(
attrs,
{|desc|
{
brief: none,
desc: desc,
args: [],
return: none,
failure: none
}
},
parse_fn_long_doc
)
fn parse_long_doc<T>(
attrs: [ast::attribute],
parse_long: fn&(doc_items: [@ast::meta_item]) -> T
) -> T {
alt doc_meta(attrs) {
some(meta) {
alt attr::get_meta_item_list(meta) {
some(list) {
parse_long(list)
}
none {
parse_long([])
}
}
}
none { parse_long([]) }
}
}
fn parse_fn_long_doc(
items: [@ast::meta_item],
brief: option<str>,
desc: option<str>
) -> fn_attrs {
fn parse_fn(attrs: [ast::attribute]) -> fn_attrs {
parse_long_doc(attrs, parse_fn_long_doc)
}
fn parse_fn_long_doc(items: [@ast::meta_item]) -> fn_attrs {
let return = attr::meta_item_value_from_list(items, "return");
let failure = attr::meta_item_value_from_list(items, "failure");
let args = parse_args(items);
{
brief: brief,
desc: desc,
args: args,
return: return,
failure: failure
@ -304,36 +267,10 @@ fn parse_fn_should_handle_undocumented_functions() {
let source = "";
let attrs = test::parse_attributes(source);
let attrs = parse_fn(attrs);
assert attrs.brief == none;
assert attrs.desc == none;
assert attrs.return == none;
assert vec::len(attrs.args) == 0u;
}
#[test]
fn parse_fn_should_parse_simple_doc_attributes() {
let source = "#[doc = \"basic\"]";
let attrs = test::parse_attributes(source);
let attrs = parse_fn(attrs);
assert attrs.desc == some("basic");
}
#[test]
fn parse_fn_should_parse_the_brief_description() {
let source = "#[doc(brief = \"short\")]";
let attrs = test::parse_attributes(source);
let attrs = parse_fn(attrs);
assert attrs.brief == some("short");
}
#[test]
fn parse_fn_should_parse_the_long_description() {
let source = "#[doc(desc = \"description\")]";
let attrs = test::parse_attributes(source);
let attrs = parse_fn(attrs);
assert attrs.desc == some("description");
}
#[test]
fn parse_fn_should_parse_the_return_value_description() {
let source = "#[doc(return = \"return value\")]";
@ -359,48 +296,6 @@ fn parse_fn_should_parse_failure_conditions() {
assert attrs.failure == some("it's the fail");
}
fn parse_const(attrs: [ast::attribute]) -> const_attrs {
parse_basic(attrs)
}
#[test]
fn should_parse_const_short_doc() {
let source = "#[doc = \"description\"]";
let attrs = test::parse_attributes(source);
let attrs = parse_const(attrs);
assert attrs.desc == some("description");
}
#[test]
fn should_parse_const_long_doc() {
let source = "#[doc(brief = \"a\", desc = \"b\")]";
let attrs = test::parse_attributes(source);
let attrs = parse_const(attrs);
assert attrs.brief == some("a");
assert attrs.desc == some("b");
}
fn parse_enum(attrs: [ast::attribute]) -> enum_attrs {
parse_basic(attrs)
}
#[test]
fn should_parse_enum_short_doc() {
let source = "#[doc = \"description\"]";
let attrs = test::parse_attributes(source);
let attrs = parse_enum(attrs);
assert attrs.desc == some("description");
}
#[test]
fn should_parse_enum_long_doc() {
let source = "#[doc(brief = \"a\", desc = \"b\")]";
let attrs = test::parse_attributes(source);
let attrs = parse_enum(attrs);
assert attrs.brief == some("a");
assert attrs.desc == some("b");
}
fn parse_variant(attrs: [ast::attribute]) -> variant_attrs {
parse_short_doc_or(
attrs,
@ -446,52 +341,16 @@ fn should_parse_variant_long_doc() {
assert attrs.desc == some("a");
}
fn parse_res(
attrs: [ast::attribute]
) -> res_attrs {
parse_short_doc_or(
attrs,
{|desc|
{
brief: none,
desc: desc,
args: []
}
},
parse_res_long_doc
)
fn parse_res(attrs: [ast::attribute]) -> res_attrs {
parse_long_doc(attrs, parse_res_long_doc)
}
fn parse_res_long_doc(
items: [@ast::meta_item],
brief: option<str>,
desc: option<str>
) -> res_attrs {
fn parse_res_long_doc(items: [@ast::meta_item]) -> res_attrs {
{
brief: brief,
desc: desc,
args: parse_args(items)
}
}
#[test]
fn should_parse_resource_short_desc() {
let source = "#[doc = \"a\"]";
let attrs = test::parse_attributes(source);
let attrs = parse_res(attrs);
assert attrs.desc == some("a");
}
#[test]
fn should_parse_resource_long_desc() {
let source = "#[doc(brief = \"a\", desc = \"b\")]";
let attrs = test::parse_attributes(source);
let attrs = parse_res(attrs);
assert attrs.brief == some("a");
assert attrs.desc == some("b");
}
#[test]
fn shoulde_parse_resource_arg() {
let source = "#[doc(args(a = \"b\"))]";
@ -501,18 +360,6 @@ fn shoulde_parse_resource_arg() {
assert attrs.args[0].desc == "b";
}
fn parse_iface(attrs: [ast::attribute]) -> iface_attrs {
parse_basic(attrs)
}
fn parse_method(attrs: [ast::attribute]) -> method_attrs {
parse_fn(attrs)
}
fn parse_impl(attrs: [ast::attribute]) -> impl_attrs {
parse_basic(attrs)
}
fn parse_type(attrs: [ast::attribute]) -> type_attrs {
parse_basic(attrs)
}

179
src/rustdoc/attr_pass.rs
View file

@ -21,14 +21,12 @@ fn run(
) -> doc::cratedoc {
let fold = fold::fold({
fold_crate: fold_crate,
fold_mod: fold_mod,
fold_item: fold_item,
fold_fn: fold_fn,
fold_const: fold_const,
fold_enum: fold_enum,
fold_res: fold_res,
fold_iface: fold_iface,
fold_impl: fold_impl,
fold_type: fold_type
fold_impl: fold_impl
with *fold::default_seq_fold(srv)
});
fold.fold_crate(fold, doc)
@ -64,6 +62,30 @@ fn should_replace_top_module_name_with_crate_name() {
assert doc.topmod.name() == "bond";
}
fn fold_item(
fold: fold::fold<astsrv::srv>,
doc: doc::itemdoc
) -> doc::itemdoc {
let srv = fold.ctxt;
let doc = fold::default_seq_fold_item(fold, doc);
let attrs = if doc.id == ast::crate_node_id {
// This is the top-level mod, use the crate attributes
astsrv::exec(srv) {|ctxt|
attr_parser::parse_basic(ctxt.ast.node.attrs)
}
} else {
parse_item_attrs(srv, doc.id, attr_parser::parse_basic)
};
{
brief: attrs.brief,
desc: attrs.desc
with doc
}
}
fn parse_item_attrs<T>(
srv: astsrv::srv,
id: doc::ast_id,
@ -79,42 +101,14 @@ fn parse_item_attrs<T>(
}
}
fn fold_mod(fold: fold::fold<astsrv::srv>, doc: doc::moddoc) -> doc::moddoc {
let srv = fold.ctxt;
let attrs = if doc.id() == ast::crate_node_id {
// This is the top-level mod, use the crate attributes
astsrv::exec(srv) {|ctxt|
attr_parser::parse_mod(ctxt.ast.node.attrs)
}
} else {
parse_item_attrs(srv, doc.id(), attr_parser::parse_mod)
};
let doc = fold::default_seq_fold_mod(fold, doc);
ret merge_mod_attrs(doc, attrs);
fn merge_mod_attrs(
doc: doc::moddoc,
attrs: attr_parser::mod_attrs
) -> doc::moddoc {
{
item: {
brief: attrs.brief,
desc: attrs.desc
with doc.item
}
with doc
}
}
}
#[test]
fn fold_mod_should_extract_mod_attributes() {
fn should_should_extract_mod_attributes() {
let doc = test::mk_doc("#[doc = \"test\"] mod a { }");
assert doc.topmod.mods()[0].desc() == some("test");
}
#[test]
fn fold_mod_should_extract_top_mod_attributes() {
fn should_extract_top_mod_attributes() {
let doc = test::mk_doc("#[doc = \"test\"];");
assert doc.topmod.desc() == some("test");
}
@ -126,6 +120,7 @@ fn fold_fn(
let srv = fold.ctxt;
let doc = fold::default_seq_fold_fn(fold, doc);
let attrs = parse_item_attrs(srv, doc.id(), attr_parser::parse_fn);
ret merge_fn_attrs(doc, attrs);
@ -134,11 +129,6 @@ fn fold_fn(
attrs: attr_parser::fn_attrs
) -> doc::fndoc {
ret {
item: {
brief: attrs.brief,
desc: attrs.desc
with doc.item
},
args: merge_arg_attrs(doc.args, attrs.args),
return: merge_ret_attrs(doc.return, attrs.return),
failure: attrs.failure
@ -179,19 +169,19 @@ fn merge_ret_attrs(
}
#[test]
fn fold_fn_should_extract_fn_attributes() {
fn should_extract_fn_attributes() {
let doc = test::mk_doc("#[doc = \"test\"] fn a() -> int { }");
assert doc.topmod.fns()[0].desc() == some("test");
}
#[test]
fn fold_fn_should_extract_arg_attributes() {
fn should_extract_fn_arg_attributes() {
let doc = test::mk_doc("#[doc(args(a = \"b\"))] fn c(a: bool) { }");
assert doc.topmod.fns()[0].args[0].desc == some("b");
}
#[test]
fn fold_fn_should_extract_return_attributes() {
fn should_extract_fn_return_attributes() {
let source = "#[doc(return = \"what\")] fn a() -> int { }";
let srv = astsrv::mk_srv_from_str(source);
let doc = extract::from_srv(srv, "");
@ -202,7 +192,7 @@ fn fold_fn_should_extract_return_attributes() {
}
#[test]
fn fold_fn_should_preserve_sig() {
fn should_preserve_fn_sig() {
let source = "fn a() -> int { }";
let srv = astsrv::mk_srv_from_str(source);
let doc = extract::from_srv(srv, "");
@ -213,30 +203,13 @@ fn fold_fn_should_preserve_sig() {
}
#[test]
fn fold_fn_should_extract_failure_conditions() {
fn should_extract_fn_failure_conditions() {
let doc = test::mk_doc("#[doc(failure = \"what\")] fn a() { }");
assert doc.topmod.fns()[0].failure == some("what");
}
fn fold_const(
fold: fold::fold<astsrv::srv>,
doc: doc::constdoc
) -> doc::constdoc {
let srv = fold.ctxt;
let attrs = parse_item_attrs(srv, doc.id(), attr_parser::parse_const);
{
item: {
brief: attrs.brief,
desc: attrs.desc
with doc.item
}
with doc
}
}
#[test]
fn fold_const_should_extract_docs() {
fn should_extract_const_docs() {
let doc = test::mk_doc("#[doc(brief = \"foo\", desc = \"bar\")]\
const a: bool = true;");
assert doc.topmod.consts()[0].brief() == some("foo");
@ -248,14 +221,9 @@ fn fold_enum(
doc: doc::enumdoc
) -> doc::enumdoc {
let srv = fold.ctxt;
let attrs = parse_item_attrs(srv, doc.id(), attr_parser::parse_enum);
let doc = fold::default_seq_fold_enum(fold, doc);
{
item: {
brief: attrs.brief,
desc: attrs.desc
with doc.item
},
variants: vec::map(doc.variants) {|variant|
let attrs = astsrv::exec(srv) {|ctxt|
alt check ctxt.ast_map.get(doc.id()) {
@ -282,7 +250,7 @@ fn fold_enum(
}
#[test]
fn fold_enum_should_extract_docs() {
fn should_extract_enum_docs() {
let doc = test::mk_doc("#[doc(brief = \"a\", desc = \"b\")]\
enum a { v }");
assert doc.topmod.enums()[0].brief() == some("a");
@ -290,7 +258,7 @@ fn fold_enum_should_extract_docs() {
}
#[test]
fn fold_enum_should_extract_variant_docs() {
fn should_extract_variant_docs() {
let doc = test::mk_doc("enum a { #[doc = \"c\"] v }");
assert doc.topmod.enums()[0].variants[0].desc == some("c");
}
@ -301,14 +269,10 @@ fn fold_res(
) -> doc::resdoc {
let srv = fold.ctxt;
let attrs = parse_item_attrs(srv, doc.id(), attr_parser::parse_fn);
let doc = fold::default_seq_fold_res(fold, doc);
let attrs = parse_item_attrs(srv, doc.id(), attr_parser::parse_res);
{
item: {
brief: attrs.brief,
desc: attrs.desc
with doc.item
},
args: vec::map(doc.args) {|doc|
alt vec::find(attrs.args) {|attr|
attr.name == doc.name
@ -327,7 +291,7 @@ fn fold_res(
}
#[test]
fn fold_res_should_extract_docs() {
fn should_extract_res_docs() {
let doc = test::mk_doc("#[doc(brief = \"a\", desc = \"b\")]\
resource r(b: bool) { }");
assert doc.topmod.resources()[0].brief() == some("a");
@ -335,7 +299,7 @@ fn fold_res_should_extract_docs() {
}
#[test]
fn fold_res_should_extract_arg_docs() {
fn should_extract_res_arg_docs() {
let doc = test::mk_doc("#[doc(args(a = \"b\"))]\
resource r(a: bool) { }");
assert doc.topmod.resources()[0].args[0].name == "a";
@ -348,14 +312,8 @@ fn fold_iface(
) -> doc::ifacedoc {
let srv = fold.ctxt;
let doc = fold::default_seq_fold_iface(fold, doc);
let attrs = parse_item_attrs(srv, doc.id(), attr_parser::parse_iface);
{
item: {
brief: attrs.brief,
desc: attrs.desc
with doc.item
},
methods: merge_method_attrs(srv, doc.id(), doc.methods)
with doc
}
@ -366,21 +324,31 @@ fn merge_method_attrs(
item_id: doc::ast_id,
docs: [doc::methoddoc]
) -> [doc::methoddoc] {
type method_attrs = (attr_parser::basic_attrs,
attr_parser::method_attrs);
// Create an assoc list from method name to attributes
let attrs = astsrv::exec(srv) {|ctxt|
let attrs: [(str, method_attrs)] = astsrv::exec(srv) {|ctxt|
alt ctxt.ast_map.get(item_id) {
ast_map::node_item(@{
node: ast::item_iface(_, methods), _
}, _) {
vec::map(methods) {|method|
(method.ident, attr_parser::parse_method(method.attrs))
(method.ident,
(attr_parser::parse_basic(method.attrs),
attr_parser::parse_method(method.attrs)
))
}
}
ast_map::node_item(@{
node: ast::item_impl(_, _, _, methods), _
}, _) {
vec::map(methods) {|method|
(method.ident, attr_parser::parse_method(method.attrs))
(method.ident,
(attr_parser::parse_basic(method.attrs),
attr_parser::parse_method(method.attrs)
))
}
}
_ { fail "unexpected item" }
@ -389,14 +357,15 @@ fn merge_method_attrs(
vec::map2(docs, attrs) {|doc, attrs|
assert doc.name == tuple::first(attrs);
let attrs = tuple::second(attrs);
let basic_attrs = tuple::first(tuple::second(attrs));
let method_attrs = tuple::second(tuple::second(attrs));
{
brief: attrs.brief,
desc: attrs.desc,
args: merge_arg_attrs(doc.args, attrs.args),
return: merge_ret_attrs(doc.return, attrs.return),
failure: attrs.failure
brief: basic_attrs.brief,
desc: basic_attrs.desc,
args: merge_arg_attrs(doc.args, method_attrs.args),
return: merge_ret_attrs(doc.return, method_attrs.return),
failure: method_attrs.failure
with doc
}
}
@ -434,14 +403,8 @@ fn fold_impl(
) -> doc::impldoc {
let srv = fold.ctxt;
let doc = fold::default_seq_fold_impl(fold, doc);
let attrs = parse_item_attrs(srv, doc.id(), attr_parser::parse_impl);
{
item: {
brief: attrs.brief,
desc: attrs.desc
with doc.item
},
methods: merge_method_attrs(srv, doc.id(), doc.methods)
with doc
}
@ -473,24 +436,6 @@ fn should_extract_impl_method_docs() {
assert doc.topmod.impls()[0].methods[0].failure == some("failure");
}
fn fold_type(
fold: fold::fold<astsrv::srv>,
doc: doc::tydoc
) -> doc::tydoc {
let srv = fold.ctxt;
let doc = fold::default_seq_fold_type(fold, doc);
let attrs = parse_item_attrs(srv, doc.id(), attr_parser::parse_type);
{
item: {
brief: attrs.brief,
desc: attrs.desc
with doc.item
}
with doc
}
}
#[test]
fn should_extract_type_docs() {
let doc = test::mk_doc(