rustdoc: Cleanup

src/rustdoc/pass.rs

+/// A single operation on the document model
+pub type Pass = {
+    name: ~str,
+    f: fn~(srv: astsrv::Srv, doc: doc::Doc) -> doc::Doc
+};
+
+pub fn run_passes(
+    srv: astsrv::Srv,
+    doc: doc::Doc,
+    passes: ~[Pass]
+) -> doc::Doc {
+    let mut passno = 0;
+    do vec::foldl(doc, passes) |doc, pass| {
+        log(debug, fmt!("pass #%d", passno));
+        passno += 1;
+        log(debug, doc);
+        do time(pass.name) {
+            pass.f(srv, doc)
+        }
+    }
+}
+
+#[test]
+fn test_run_passes() {
+    fn pass1(
+        _srv: astsrv::Srv,
+        doc: doc::Doc
+    ) -> doc::Doc {
+        doc::Doc_({
+            pages: ~[
+                doc::CratePage({
+                    topmod: doc::ModDoc_({
+                        item: {
+                            name: doc.cratemod().name() + ~"two",
+                            .. doc.cratemod().item
+                        },
+                        items: ~[],
+                        index: None
+                    })
+                })
+            ]
+        })
+    }
+    fn pass2(
+        _srv: astsrv::Srv,
+        doc: doc::Doc
+    ) -> doc::Doc {
+        doc::Doc_({
+            pages: ~[
+                doc::CratePage({
+                    topmod: doc::ModDoc_({
+                        item: {
+                            name: doc.cratemod().name() + ~"three",
+                            .. doc.cratemod().item
+                        },
+                        items: ~[],
+                        index: None
+                    })
+                })
+            ]
+        })
+    }
+    let source = ~"";
+    do astsrv::from_str(source) |srv| {
+        let passes = ~[
+            {
+                name: ~"",
+                f: pass1
+            },
+            {
+                name: ~"",
+                f: pass2
+            }
+        ];
+        let doc = extract::from_srv(srv, ~"one");
+        let doc = run_passes(srv, doc, passes);
+        assert doc.cratemod().name() == ~"onetwothree";
+    }
+}

src/rustdoc/rustdoc.rc

@@ -10,11 +10,10 @@
 #[crate_type = "bin"];
 
 #[no_core];
-
 #[legacy_modes];
 
-#[allow(vecs_implicitly_copyable,
-        non_implicitly_copyable_typarams)];
+#[allow(vecs_implicitly_copyable)];
+#[allow(non_implicitly_copyable_typarams)];
 
 extern mod core(vers = "0.4");
 extern mod std(vers = "0.4");
@@ -24,6 +23,7 @@ extern mod syntax(vers = "0.4");
 use core::*;
 use std::par;
 
+mod pass;
 mod config;
 mod parse;
 mod extract;

src/rustdoc/rustdoc.rs

-//! Some utility interfaces
-
 use doc::ItemUtils;
 use doc::Item;
-use doc::util;
-
-/// A single operation on the document model
-type Pass = {
-    name: ~str,
-    f: fn~(srv: astsrv::Srv, doc: doc::Doc) -> doc::Doc
-};
-
-fn run_passes(
-    srv: astsrv::Srv,
-    doc: doc::Doc,
-    passes: ~[Pass]
-) -> doc::Doc {
-    let mut passno = 0;
-    do vec::foldl(doc, passes) |doc, pass| {
-        log(debug, fmt!("pass #%d", passno));
-        passno += 1;
-        log(debug, doc);
-        do time(pass.name) {
-            pass.f(srv, doc)
-        }
-    }
-}
-
-#[test]
-fn test_run_passes() {
-    fn pass1(
-        _srv: astsrv::Srv,
-        doc: doc::Doc
-    ) -> doc::Doc {
-        doc::Doc_({
-            pages: ~[
-                doc::CratePage({
-                    topmod: doc::ModDoc_({
-                        item: {
-                            name: doc.cratemod().name() + ~"two",
-                            .. doc.cratemod().item
-                        },
-                        items: ~[],
-                        index: None
-                    })
-                })
-            ]
-        })
-    }
-    fn pass2(
-        _srv: astsrv::Srv,
-        doc: doc::Doc
-    ) -> doc::Doc {
-        doc::Doc_({
-            pages: ~[
-                doc::CratePage({
-                    topmod: doc::ModDoc_({
-                        item: {
-                            name: doc.cratemod().name() + ~"three",
-                            .. doc.cratemod().item
-                        },
-                        items: ~[],
-                        index: None
-                    })
-                })
-            ]
-        })
-    }
-    let source = ~"";
-    do astsrv::from_str(source) |srv| {
-        let passes = ~[
-            {
-                name: ~"",
-                f: pass1
-            },
-            {
-                name: ~"",
-                f: pass2
-            }
-        ];
-        let doc = extract::from_srv(srv, ~"one");
-        let doc = run_passes(srv, doc, passes);
-        assert doc.cratemod().name() == ~"onetwothree";
-    }
-}
+use pass::Pass;
+use config::Config;
 
 fn main(args: ~[~str]) {
 
@@ -92,8 +11,8 @@ fn main(args: ~[~str]) {
     }
 
     let config = match config::parse_config(args) {
-      result::Ok(config) => config,
-      result::Err(err) => {
+      Ok(config) => config,
+      Err(err) => {
         io::println(fmt!("error: %s", err));
         return;
       }
@@ -102,43 +21,67 @@ fn main(args: ~[~str]) {
     run(config);
 }
 
-fn time<T>(what: ~str, f: fn() -> T) -> T {
-    let start = std::time::precise_time_s();
-    let rv = f();
-    let end = std::time::precise_time_s();
-    info!("time: %3.3f s    %s", end - start, what);
-    return rv;
-}
-
 /// Runs rustdoc over the given file
-fn run(config: config::Config) {
+fn run(config: Config) {
 
     let source_file = config.input_crate;
+
+    // Create an AST service from the source code
     do astsrv::from_file(source_file.to_str()) |srv| {
+
+        // Just time how long it takes for the AST to become available
         do time(~"wait_ast") {
             do astsrv::exec(srv) |_ctxt| { }
         };
+
+        // Extract the initial doc tree from the AST. This contains
+        // just names and node ids.
         let doc = time(~"extract", || {
             let default_name = source_file;
             extract::from_srv(srv, default_name.to_str())
         });
-        run_passes(srv, doc, ~[
+
+        // Refine and publish the document
+        pass::run_passes(srv, doc, ~[
+            // Generate type and signature strings
             tystr_pass::mk_pass(),
+            // Record the full paths to various nodes
             path_pass::mk_pass(),
+            // Extract the docs attributes and attach them to doc nodes
             attr_pass::mk_pass(),
+            // Perform various text escaping
             escape_pass::mk_pass(),
+            // Remove things marked doc(hidden)
             prune_hidden_pass::mk_pass(),
+            // Extract brief documentation from the full descriptions
             desc_to_brief_pass::mk_pass(),
+            // Massage the text to remove extra indentation
             unindent_pass::mk_pass(),
+            // Split text into multiple sections according to headers
             sectionalize_pass::mk_pass(),
+            // Trim extra spaces from text
             trim_pass::mk_pass(),
+            // Sort items by name
             sort_item_name_pass::mk_pass(),
+            // Sort items again by kind
             sort_item_type_pass::mk_pass(),
+            // Create indexes appropriate for markdown
             markdown_index_pass::mk_pass(config),
+            // Break the document into pages if required by the
+            // output format
             page_pass::mk_pass(config.output_style),
+            // Render
             markdown_pass::mk_pass(
                 markdown_writer::make_writer_factory(config)
             )
         ]);
     }
 }
+
+fn time<T>(what: ~str, f: fn() -> T) -> T {
+    let start = std::time::precise_time_s();
+    let rv = f();
+    let end = std::time::precise_time_s();
+    info!("time: %3.3f s    %s", end - start, what);
+    return rv;
+}