rustdoc: Write markdown for function signatures

Author: brson

src/rustdoc/attr_pass.rs

@@ -129,13 +129,11 @@ fn fold_fn(
         attrs: attr_parser::fn_attrs
     ) -> doc::fndoc {
         ret ~{
-            id: doc.id,
-            name: doc.name,
             brief: attrs.brief,
             desc: attrs.desc,
             args: merge_arg_attrs(doc.args, attrs.args),
-            return: merge_ret_attrs(doc.return, attrs.return),
-            sig: none
+            return: merge_ret_attrs(doc.return, attrs.return)
+            with *doc
         };
     }
 
@@ -207,4 +205,15 @@ fn fold_fn_should_extract_return_attributes() {
     let fold = fold::default_seq_fold(srv);
     let doc = fold_fn(fold, doc.topmod.fns[0]);
     assert option::get(doc.return).desc == some("what");
+}
+
+#[test]
+fn fold_fn_should_preserve_sig() {
+    let source = "fn a() -> int { }";
+    let srv = astsrv::mk_srv_from_str(source);
+    let doc = extract::from_srv(srv, "");
+    let doc = tystr_pass::mk_pass()(srv, doc);
+    let fold = fold::default_seq_fold(srv);
+    let doc = fold_fn(fold, doc.topmod.fns[0]);
+    assert doc.sig == some("fn a() -> int");
 }

src/rustdoc/gen.rs

@@ -107,12 +107,37 @@ fn write_fn(
     doc: doc::fndoc
 ) {
     write_header(ctxt, h3, #fmt("Function `%s`", doc.name));
+    write_sig(ctxt, doc.sig);
     write_brief(ctxt, doc.brief);
     write_desc(ctxt, doc.desc);
     write_args(ctxt, doc.args);
     write_return(ctxt, doc.return);
 }
 
+fn write_sig(ctxt: ctxt, sig: option<str>) {
+    alt sig {
+      some(sig) {
+        ctxt.w.write_line("```");
+        ctxt.w.write_line(#fmt("%s", sig));
+        ctxt.w.write_line("```");
+        ctxt.w.write_line("");
+      }
+      none { fail "unimplemented" }
+    }
+}
+
+#[test]
+fn should_write_the_function_signature() {
+    let markdown = test::render("#[doc = \"f\"] fn a() { }");
+    assert str::contains(markdown, "```\nfn a()\n```");
+}
+
+#[test]
+fn should_insert_blank_line_after_fn_signature() {
+    let markdown = test::render("#[doc = \"f\"] fn a() { }");
+    assert str::contains(markdown, "fn a()\n```\n\n");
+}
+
 fn write_brief(
     ctxt: ctxt,
     brief: option<str>
@@ -254,9 +279,13 @@ mod test {
     fn render(source: str) -> str {
         let srv = astsrv::mk_srv_from_str(source);
         let doc = extract::from_srv(srv, "");
+        #debug("doc (extract): %?", doc);
         let doc = tystr_pass::mk_pass()(srv, doc);
+        #debug("doc (tystr): %?", doc);
         let doc = path_pass::mk_pass()(srv, doc);
+        #debug("doc (path): %?", doc);
         let doc = attr_pass::mk_pass()(srv, doc);
+        #debug("doc (attr): %?", doc);
         let markdown = write_markdown_str(doc);
         #debug("markdown: %s", markdown);
         markdown
@@ -299,9 +328,9 @@ mod test {
     }
 
     #[test]
-    fn should_leave_blank_line_between_fn_header_and_brief() {
+    fn should_leave_blank_line_between_fn_header_and_sig() {
         let markdown = render("#[doc(brief = \"brief\")] fn a() { }");
-        assert str::contains(markdown, "Function `a`\n\nbrief");
+        assert str::contains(markdown, "Function `a`\n\n```\nfn a()");
     }
 
     #[test]