rustdoc: Parse module docs

Author: brson

src/rustdoc/attr_parser.rs

@@ -10,12 +10,17 @@ import rustc::front::attr;
 import core::tuple;
 
 export crate_attrs, fn_attrs, arg_attrs;
-export parse_crate, parse_fn;
+export parse_crate, parse_mod, parse_fn;
 
 type crate_attrs = {
     name: option<str>
 };
 
+type mod_attrs = {
+    brief: option<str>,
+    desc: option<str>
+};
+
 type fn_attrs = {
     brief: option<str>,
     desc: option<str>,
@@ -80,51 +85,121 @@ fn should_not_extract_crate_name_if_no_name_value_in_link_attribute() {
     assert attrs.name == none;
 }
 
-fn parse_fn(
-    attrs: [ast::attribute]
-) -> fn_attrs {
+fn parse_mod(attrs: [ast::attribute]) -> mod_attrs {
+    parse_short_doc_or(
+        attrs,
+        {|desc|
+            {
+                brief: none,
+                desc: desc
+            }
+        },
+        parse_mod_long_doc
+    )
+}
 
-    let no_attrs = {
-        brief: none,
-        desc: none,
-        args: [],
-        return: none
-    };
+fn parse_mod_long_doc(
+    _items: [@ast::meta_item],
+    brief: option<str>,
+    desc: option<str>
+) -> mod_attrs {
+    {
+        brief: brief,
+        desc: desc
+    }
+}
 
-    ret alt doc_meta(attrs) {
+#[test]
+fn parse_mod_should_handle_undocumented_mods() {
+    let source = "";
+    let attrs = test::parse_attributes(source);
+    let attrs = parse_mod(attrs);
+    assert attrs.brief == none;
+    assert attrs.desc == none;
+}
+
+#[test]
+fn parse_mod_should_parse_simple_doc_attributes() {
+    let source = "#[doc = \"basic\"]";
+    let attrs = test::parse_attributes(source);
+    let attrs = parse_mod(attrs);
+    assert attrs.desc == some("basic");
+}
+
+#[test]
+fn parse_mod_should_parse_the_brief_description() {
+    let source = "#[doc(brief = \"short\")]";
+    let attrs = test::parse_attributes(source);
+    let attrs = parse_mod(attrs);
+    assert attrs.brief == some("short");
+}
+
+#[test]
+fn parse_mod_should_parse_the_long_description() {
+    let source = "#[doc(desc = \"description\")]";
+    let attrs = test::parse_attributes(source);
+    let attrs = parse_mod(attrs);
+    assert attrs.desc == some("description");
+}
+
+fn parse_short_doc_or<T>(
+    attrs: [ast::attribute],
+    handle_short: fn&(
+        short_desc: option<str>
+    ) -> T,
+    parse_long: fn&(
+        doc_items: [@ast::meta_item],
+        brief: option<str>,
+        desc: option<str>
+    ) -> T
+) -> T {
+    alt doc_meta(attrs) {
       some(meta) {
         alt attr::get_meta_item_value_str(meta) {
-          some(desc) {
-            {
-                brief: none,
-                desc: some(desc),
-                args: [],
-                return: none
-            }
-          }
+          some(desc) { handle_short(some(desc)) }
           none. {
             alt attr::get_meta_item_list(meta) {
               some(list) {
-                parse_fn_(list)
+                let brief = attr::meta_item_value_from_list(list, "brief");
+                let desc = attr::meta_item_value_from_list(list, "desc");
+                parse_long(list, brief, desc)
               }
               none. {
-                no_attrs
+                handle_short(none)
               }
             }
           }
         }
       }
       none. {
-        no_attrs
+        handle_short(none)
       }
-    };
+    }
+}
+
+fn parse_fn(
+    attrs: [ast::attribute]
+) -> fn_attrs {
+
+    parse_short_doc_or(
+        attrs,
+        {|desc|
+            {
+                brief: none,
+                desc: desc,
+                args: [],
+                return: none
+            }
+        },
+        parse_fn_long_doc
+    )
 }
 
-fn parse_fn_(
-    items: [@ast::meta_item]
+fn parse_fn_long_doc(
+    items: [@ast::meta_item],
+    brief: option<str>,
+    desc: option<str>
 ) -> fn_attrs {
-    let brief = attr::meta_item_value_from_list(items, "brief");
-    let desc = attr::meta_item_value_from_list(items, "desc");
     let return = attr::meta_item_value_from_list(items, "return");
 
     let args = alt attr::meta_item_list_from_list(items, "args") {
@@ -149,6 +224,58 @@ fn parse_fn_(
     }
 }
 
+#[test]
+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\")]";
+    let attrs = test::parse_attributes(source);
+    let attrs = parse_fn(attrs);
+    assert attrs.return == some("return value");
+}
+
+#[test]
+fn parse_fn_should_parse_the_argument_descriptions() {
+    let source = "#[doc(args(a = \"arg a\", b = \"arg b\"))]";
+    let attrs = test::parse_attributes(source);
+    let attrs = parse_fn(attrs);
+    assert attrs.args[0] == {name: "a", desc: "arg a"};
+    assert attrs.args[1] == {name: "b", desc: "arg b"};
+}
+
 #[cfg(test)]
 mod test {
 
@@ -169,56 +296,4 @@ mod test {
 
         parser::parse_outer_attributes(parser)
     }
-
-    #[test]
-    fn parse_fn_should_handle_undocumented_functions() {
-        let source = "";
-        let attrs = 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 = 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 = 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 = 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\")]";
-        let attrs = parse_attributes(source);
-        let attrs = parse_fn(attrs);
-        assert attrs.return == some("return value");
-    }
-
-    #[test]
-    fn parse_fn_should_parse_the_argument_descriptions() {
-        let source = "#[doc(args(a = \"arg a\", b = \"arg b\"))]";
-        let attrs = parse_attributes(source);
-        let attrs = parse_fn(attrs);
-        assert attrs.args[0] == {name: "a", desc: "arg a"};
-        assert attrs.args[1] == {name: "b", desc: "arg b"};
-    }
 }