From 29ac3c811d0235b51e17519d7b212287ca27e626 Mon Sep 17 00:00:00 2001
From: Brian Anderson <banderson@mozilla.com>
Date: Tue, 6 Mar 2012 16:51:40 -0800
Subject: [PATCH] rustdoc: Put brief descriptions in the indexes

---
 src/rustdoc/doc.rs                 |  2 ++
 src/rustdoc/markdown_index_pass.rs | 15 +++++++++++++++
 src/rustdoc/markdown_pass.rs       | 13 ++++++++++++-
 3 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/src/rustdoc/doc.rs b/src/rustdoc/doc.rs
index ccee1335835..288bccf0d41 100644
--- a/src/rustdoc/doc.rs
+++ b/src/rustdoc/doc.rs
@@ -131,12 +131,14 @@ Fields:
 
 * kind - The type of thing being indexed, e.g. 'Module'
 * name - The name of the thing
+* brief - The brief description
 * link - A format-specific string representing the link target
 
 "]
 type index_entry = {
     kind: str,
     name: str,
+    brief: option<str>,
     link: str
 };
 
diff --git a/src/rustdoc/markdown_index_pass.rs b/src/rustdoc/markdown_index_pass.rs
index 9c23b21dfc9..f7481da3c0b 100644
--- a/src/rustdoc/markdown_index_pass.rs
+++ b/src/rustdoc/markdown_index_pass.rs
@@ -63,6 +63,7 @@ fn item_to_entry(
     {
         kind: markdown_pass::header_kind(doc),
         name: markdown_pass::header_name(doc),
+        brief: doc.brief(),
         link: link
     }
 }
@@ -100,11 +101,13 @@ fn should_index_mod_contents() {
     assert option::get(doc.cratemod().index).entries[0] == {
         kind: "Module",
         name: "a",
+        brief: none,
         link: "#module-a"
     };
     assert option::get(doc.cratemod().index).entries[1] == {
         kind: "Function",
         name: "b",
+        brief: none,
         link: "#function-b"
     };
 }
@@ -118,15 +121,26 @@ fn should_index_mod_contents_multi_page() {
     assert option::get(doc.cratemod().index).entries[0] == {
         kind: "Module",
         name: "a",
+        brief: none,
         link: "a.html"
     };
     assert option::get(doc.cratemod().index).entries[1] == {
         kind: "Function",
         name: "b",
+        brief: none,
         link: "#function-b"
     };
 }
 
+#[test]
+fn should_add_brief_desc_to_index() {
+    let doc = test::mk_doc(
+        config::doc_per_mod,
+        "#[doc(brief = \"test\")] mod a { }"
+    );
+    assert option::get(doc.cratemod().index).entries[0].brief == some("test");
+}
+
 #[cfg(test)]
 mod test {
     fn mk_doc(output_style: config::output_style, source: str) -> doc::doc {
@@ -136,6 +150,7 @@ mod test {
                 with config::default_config("whatever")
             };
             let doc = extract::from_srv(srv, "");
+            let doc = attr_pass::mk_pass().f(srv, doc);
             let doc = path_pass::mk_pass().f(srv, doc);
             run(srv, doc, config)
         }
diff --git a/src/rustdoc/markdown_pass.rs b/src/rustdoc/markdown_pass.rs
index 36eabf63879..e531fb5e6e6 100644
--- a/src/rustdoc/markdown_pass.rs
+++ b/src/rustdoc/markdown_pass.rs
@@ -283,7 +283,12 @@ fn write_index(ctxt: ctxt, index: doc::index) {
     for entry in index.entries {
         let header = header_text_(entry.kind, entry.name);
         let id = entry.link;
-        ctxt.w.write_line(#fmt("* [%s](%s)", header, id));
+        if option::is_some(entry.brief) {
+            ctxt.w.write_line(#fmt("* [%s](%s) - %s",
+                                   header, id, option::get(entry.brief)));
+        } else {
+            ctxt.w.write_line(#fmt("* [%s](%s)", header, id));
+        }
     }
     ctxt.w.write_line("");
 }
@@ -298,6 +303,12 @@ fn should_write_index() {
     );
 }
 
+#[test]
+fn should_write_index_brief() {
+    let markdown = test::render("#[doc(brief = \"test\")] mod a { }");
+    assert str::contains(markdown, "(#module-a) - test\n");
+}
+
 #[test]
 fn should_not_write_index_if_no_entries() {
     let markdown = test::render("");