From ac8b2c83542fdd470c775e0a9e99cd2a26afbf36 Mon Sep 17 00:00:00 2001
From: Brian Anderson <banderson@mozilla.com>
Date: Thu, 8 Mar 2012 13:41:14 -0800
Subject: [PATCH] rustdoc: Don't bother reporting the type of return values
---
src/rustdoc/doc.rs | 3 +-
src/rustdoc/extract.rs | 9 +-
src/rustdoc/markdown_pass.rs | 42 ++----
src/rustdoc/prune_undoc_details_pass.rs | 42 +-----
src/rustdoc/tystr_pass.rs | 163 ------------------------
5 files changed, 19 insertions(+), 240 deletions(-)
diff --git a/src/rustdoc/doc.rs b/src/rustdoc/doc.rs
index ebd0896f782..896d1a9dfa8 100644
--- a/src/rustdoc/doc.rs
+++ b/src/rustdoc/doc.rs
@@ -70,8 +70,7 @@ type argdoc = {
};
type retdoc = {
- desc: option<str>,
- ty: option<str>
+ desc: option<str>
};
type enumdoc = {
diff --git a/src/rustdoc/extract.rs b/src/rustdoc/extract.rs
index 2ba3a397c26..f52ac727c02 100644
--- a/src/rustdoc/extract.rs
+++ b/src/rustdoc/extract.rs
@@ -136,8 +136,7 @@ fn fndoc_from_fn(
item: itemdoc,
args: argdocs_from_args(decl.inputs),
return: {
- desc: none,
- ty: none
+ desc: none
},
failure: none,
sig: none
@@ -253,8 +252,7 @@ fn ifacedoc_from_iface(
desc: none,
args: argdocs_from_args(method.decl.inputs),
return: {
- desc: none,
- ty: none
+ desc: none
},
failure: none,
sig: none
@@ -296,8 +294,7 @@ fn impldoc_from_impl(
desc: none,
args: argdocs_from_args(method.decl.inputs),
return: {
- desc: none,
- ty: none
+ desc: none
},
failure: none,
sig: none
diff --git a/src/rustdoc/markdown_pass.rs b/src/rustdoc/markdown_pass.rs
index a4d9c1fecf8..32c178de00b 100644
--- a/src/rustdoc/markdown_pass.rs
+++ b/src/rustdoc/markdown_pass.rs
@@ -531,19 +531,10 @@ fn write_return(
ctxt: ctxt,
doc: doc::retdoc
) {
- alt doc.ty {
- some(ty) {
- ctxt.w.write_str(#fmt("Returns `%s`", ty));
- alt doc.desc {
- some(d) {
- ctxt.w.write_line(#fmt(" - %s", d));
- ctxt.w.write_line("");
- }
- none {
- ctxt.w.write_line("");
- ctxt.w.write_line("");
- }
- }
+ alt doc.desc {
+ some(d) {
+ ctxt.w.write_line(#fmt("Returns - %s", d));
+ ctxt.w.write_line("");
}
none { }
}
@@ -551,17 +542,18 @@ fn write_return(
#[test]
fn should_write_return_type_on_new_line() {
- let markdown = test::render("fn a() -> int { }");
- assert str::contains(markdown, "\nReturns `int`");
+ let markdown = test::render(
+ "#[doc(return = \"test\")] fn a() -> int { }");
+ assert str::contains(markdown, "\nReturns - test");
}
#[test]
fn should_write_blank_line_between_return_type_and_next_header() {
let markdown = test::render(
- "fn a() -> int { } \
+ "#[doc(return = \"test\")] fn a() -> int { } \
fn b() -> int { }"
);
- assert str::contains(markdown, "Returns `int`\n\n##");
+ assert str::contains(markdown, "Returns - test\n\n##");
}
#[test]
@@ -578,14 +570,6 @@ fn should_write_blank_line_after_return_description() {
assert str::contains(markdown, "blorp\n\n");
}
-#[test]
-fn should_write_return_description_on_same_line_as_type() {
- let markdown = test::render(
- "#[doc(return = \"blorp\")] fn a() -> int { }"
- );
- assert str::contains(markdown, "Returns `int` - blorp");
-}
-
fn write_failure(ctxt: ctxt, str: option<str>) {
alt str {
some(str) {
@@ -823,8 +807,8 @@ fn should_not_write_iface_method_arguments_if_none() {
#[test]
fn should_write_iface_method_return_info() {
let markdown = test::render(
- "iface a { fn a() -> int; }");
- assert str::contains(markdown, "Returns `int`");
+ "iface a { #[doc(return = \"test\")] fn a() -> int; }");
+ assert str::contains(markdown, "Returns - test");
}
#[test]
@@ -905,8 +889,8 @@ fn should_not_write_impl_method_arguments_if_none() {
#[test]
fn should_write_impl_method_return_info() {
let markdown = test::render(
- "impl a for int { fn a() -> int { } }");
- assert str::contains(markdown, "Returns `int`");
+ "impl a for int { #[doc(return = \"test\")] fn a() -> int { } }");
+ assert str::contains(markdown, "Returns - test");
}
#[test]
diff --git a/src/rustdoc/prune_undoc_details_pass.rs b/src/rustdoc/prune_undoc_details_pass.rs
index 24855db7872..dc4194e0fc7 100644
--- a/src/rustdoc/prune_undoc_details_pass.rs
+++ b/src/rustdoc/prune_undoc_details_pass.rs
@@ -31,8 +31,7 @@ fn fold_fn(
let doc = fold::default_seq_fold_fn(fold, doc);
{
- args: prune_args(doc.args),
- return: prune_return(doc.return)
+ args: prune_args(doc.args)
with doc
}
}
@@ -47,35 +46,12 @@ fn prune_args(docs: [doc::argdoc]) -> [doc::argdoc] {
}
}
-fn prune_return(doc: doc::retdoc) -> doc::retdoc {
- {
- ty: if option::is_some(doc.desc) {
- doc.ty
- } else {
- none
- }
- with doc
- }
-}
-
#[test]
fn should_elide_undocumented_arguments() {
let doc = test::mk_doc("#[doc = \"hey\"] fn a(b: int) { }");
assert vec::is_empty(doc.cratemod().fns()[0].args);
}
-#[test]
-fn should_elide_undocumented_return_values() {
- let source = "#[doc = \"fonz\"] fn a() -> int { }";
- astsrv::from_str(source) {|srv|
- let doc = extract::from_srv(srv, "");
- let doc = tystr_pass::mk_pass().f(srv, doc);
- let doc = attr_pass::mk_pass().f(srv, doc);
- let doc = run(srv, doc);
- assert doc.cratemod().fns()[0].return.ty == none;
- }
-}
-
fn fold_res(
fold: fold::fold<()>,
doc: doc::resdoc
@@ -110,8 +86,7 @@ fn fold_iface(
fn prune_methods(docs: [doc::methoddoc]) -> [doc::methoddoc] {
par::anymap(docs) {|doc|
{
- args: prune_args(doc.args),
- return: prune_return(doc.return)
+ args: prune_args(doc.args)
with doc
}
}
@@ -123,12 +98,6 @@ fn should_elide_undocumented_iface_method_args() {
assert vec::is_empty(doc.cratemod().ifaces()[0].methods[0].args);
}
-#[test]
-fn should_elide_undocumented_iface_method_return_values() {
- let doc = test::mk_doc("#[doc = \"hey\"] iface i { fn a() -> int; }");
- assert doc.cratemod().ifaces()[0].methods[0].return.ty == none;
-}
-
fn fold_impl(
fold: fold::fold<()>,
doc: doc::impldoc
@@ -148,13 +117,6 @@ fn should_elide_undocumented_impl_method_args() {
assert vec::is_empty(doc.cratemod().impls()[0].methods[0].args);
}
-#[test]
-fn should_elide_undocumented_impl_method_return_values() {
- let doc = test::mk_doc(
- "#[doc = \"hey\"] impl i for int { fn a() -> int { } }");
- assert doc.cratemod().impls()[0].methods[0].return.ty == none;
-}
-
#[cfg(test)]
mod test {
fn mk_doc(source: str) -> doc::doc {
diff --git a/src/rustdoc/tystr_pass.rs b/src/rustdoc/tystr_pass.rs
index 63b4d053abb..2188da77df1 100644
--- a/src/rustdoc/tystr_pass.rs
+++ b/src/rustdoc/tystr_pass.rs
@@ -40,7 +40,6 @@ fn fold_fn(
let srv = fold.ctxt;
{
- return: merge_ret_ty(srv, doc.id(), doc.return),
sig: get_fn_sig(srv, doc.id())
with doc
}
@@ -75,88 +74,6 @@ fn should_add_native_fn_sig() {
assert doc.cratemod().nmods()[0].fns[0].sig == some("fn a() -> int");
}
-fn merge_ret_ty(
- srv: astsrv::srv,
- fn_id: doc::ast_id,
- doc: doc::retdoc
-) -> doc::retdoc {
- alt get_ret_ty(srv, fn_id) {
- some(ty) {
- {
- ty: some(ty)
- with doc
- }
- }
- none { doc }
- }
-}
-
-fn get_ret_ty(srv: astsrv::srv, fn_id: doc::ast_id) -> option<str> {
- astsrv::exec(srv) {|ctxt|
- alt check ctxt.ast_map.get(fn_id) {
- ast_map::node_item(@{
- node: ast::item_fn(decl, _, _), _
- }, _) |
- ast_map::node_native_item(@{
- node: ast::native_item_fn(decl, _), _
- }, _, _) {
- ret_ty_to_str(decl)
- }
- }
- }
-}
-
-fn ret_ty_to_str(decl: ast::fn_decl) -> option<str> {
- if decl.output.node != ast::ty_nil {
- some(pprust::ty_to_str(decl.output))
- } else {
- // Nil-typed return values are not interesting
- none
- }
-}
-
-#[test]
-fn should_add_fn_ret_types() {
- let doc = test::mk_doc("fn a() -> int { }");
- assert doc.cratemod().fns()[0].return.ty == some("int");
-}
-
-#[test]
-fn should_not_add_nil_ret_type() {
- let doc = test::mk_doc("fn a() { }");
- assert doc.cratemod().fns()[0].return.ty == none;
-}
-
-#[test]
-fn should_add_native_fn_ret_types() {
- let doc = test::mk_doc("native mod a { fn a() -> int; }");
- assert doc.cratemod().nmods()[0].fns[0].return.ty == some("int");
-}
-
-fn get_arg_tys(srv: astsrv::srv, fn_id: doc::ast_id) -> [(str, str)] {
- astsrv::exec(srv) {|ctxt|
- alt check ctxt.ast_map.get(fn_id) {
- ast_map::node_item(@{
- node: ast::item_fn(decl, _, _), _
- }, _) |
- ast_map::node_item(@{
- node: ast::item_res(decl, _, _, _, _), _
- }, _) |
- ast_map::node_native_item(@{
- node: ast::native_item_fn(decl, _), _
- }, _, _) {
- decl_arg_tys(decl)
- }
- }
- }
-}
-
-fn decl_arg_tys(decl: ast::fn_decl) -> [(str, str)] {
- par::seqmap(decl.inputs) {|arg|
- (arg.ident, pprust::ty_to_str(arg.ty))
- }
-}
-
fn fold_const(
fold: fold::fold<astsrv::srv>,
doc: doc::constdoc
@@ -265,68 +182,12 @@ fn merge_methods(
) -> [doc::methoddoc] {
par::anymap(docs) {|doc|
{
- return: merge_method_ret_ty(
- srv,
- item_id,
- doc.return,
- doc.name),
sig: get_method_sig(srv, item_id, doc.name)
with doc
}
}
}
-fn merge_method_ret_ty(
- srv: astsrv::srv,
- item_id: doc::ast_id,
- doc: doc::retdoc,
- method_name: str
-) -> doc::retdoc {
- alt get_method_ret_ty(srv, item_id, method_name) {
- some(ty) {
- {
- ty: some(ty)
- with doc
- }
- }
- none { doc }
- }
-}
-
-fn get_method_ret_ty(
- srv: astsrv::srv,
- item_id: doc::ast_id,
- method_name: str
-) -> option<str> {
- astsrv::exec(srv) {|ctxt|
- alt ctxt.ast_map.get(item_id) {
- ast_map::node_item(@{
- node: ast::item_iface(_, methods), _
- }, _) {
- alt check vec::find(methods) {|method|
- method.ident == method_name
- } {
- some(method) {
- ret_ty_to_str(method.decl)
- }
- }
- }
- ast_map::node_item(@{
- node: ast::item_impl(_, _, _, methods), _
- }, _) {
- alt check vec::find(methods) {|method|
- method.ident == method_name
- } {
- some(method) {
- ret_ty_to_str(method.decl)
- }
- }
- }
- _ { fail }
- }
- }
-}
-
fn get_method_sig(
srv: astsrv::srv,
item_id: doc::ast_id,
@@ -366,18 +227,6 @@ fn should_add_iface_method_sigs() {
assert doc.cratemod().ifaces()[0].methods[0].sig == some("fn a() -> int");
}
-#[test]
-fn should_add_iface_method_ret_types() {
- let doc = test::mk_doc("iface i { fn a() -> int; }");
- assert doc.cratemod().ifaces()[0].methods[0].return.ty == some("int");
-}
-
-#[test]
-fn should_not_add_iface_method_nil_ret_type() {
- let doc = test::mk_doc("iface i { fn a(); }");
- assert doc.cratemod().ifaces()[0].methods[0].return.ty == none;
-}
-
fn fold_impl(
fold: fold::fold<astsrv::srv>,
doc: doc::impldoc
@@ -431,18 +280,6 @@ fn should_add_impl_method_sigs() {
assert doc.cratemod().impls()[0].methods[0].sig == some("fn a() -> int");
}
-#[test]
-fn should_add_impl_method_ret_types() {
- let doc = test::mk_doc("impl i for int { fn a() -> int { fail } }");
- assert doc.cratemod().impls()[0].methods[0].return.ty == some("int");
-}
-
-#[test]
-fn should_not_add_impl_method_nil_ret_type() {
- let doc = test::mk_doc("impl i for int { fn a() { } }");
- assert doc.cratemod().impls()[0].methods[0].return.ty == none;
-}
-
fn fold_type(
fold: fold::fold<astsrv::srv>,
doc: doc::tydoc