From c32cde16ab1cd7d8483d176591c22dbac3520833 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Fri, 21 Sep 2012 17:10:46 -0700 Subject: [PATCH] rustdoc: Cleanup --- src/rustdoc/pass.rs | 79 ++++++++++++++++++ src/rustdoc/rustdoc.rc | 6 +- src/rustdoc/rustdoc.rs | 179 ++++++++++++++--------------------------- 3 files changed, 143 insertions(+), 121 deletions(-) create mode 100644 src/rustdoc/pass.rs diff --git a/src/rustdoc/pass.rs b/src/rustdoc/pass.rs new file mode 100644 index 00000000000..0ceccda209d --- /dev/null +++ b/src/rustdoc/pass.rs @@ -0,0 +1,79 @@ +/// 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"; + } +} diff --git a/src/rustdoc/rustdoc.rc b/src/rustdoc/rustdoc.rc index 1ca4c347ba2..adde20e0209 100644 --- a/src/rustdoc/rustdoc.rc +++ b/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; diff --git a/src/rustdoc/rustdoc.rs b/src/rustdoc/rustdoc.rs index b86955afb00..edbf5ca1a94 100755 --- a/src/rustdoc/rustdoc.rs +++ b/src/rustdoc/rustdoc.rs @@ -1,88 +1,7 @@ -//! 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,6 +21,63 @@ fn main(args: ~[~str]) { run(config); } +/// Runs rustdoc over the given file +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()) + }); + + // 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(what: ~str, f: fn() -> T) -> T { let start = std::time::precise_time_s(); let rv = f(); @@ -109,36 +85,3 @@ fn time(what: ~str, f: fn() -> T) -> T { info!("time: %3.3f s %s", end - start, what); return rv; } - -/// Runs rustdoc over the given file -fn run(config: config::Config) { - - let source_file = config.input_crate; - do astsrv::from_file(source_file.to_str()) |srv| { - do time(~"wait_ast") { - do astsrv::exec(srv) |_ctxt| { } - }; - let doc = time(~"extract", || { - let default_name = source_file; - extract::from_srv(srv, default_name.to_str()) - }); - run_passes(srv, doc, ~[ - tystr_pass::mk_pass(), - path_pass::mk_pass(), - attr_pass::mk_pass(), - escape_pass::mk_pass(), - prune_hidden_pass::mk_pass(), - desc_to_brief_pass::mk_pass(), - unindent_pass::mk_pass(), - sectionalize_pass::mk_pass(), - trim_pass::mk_pass(), - sort_item_name_pass::mk_pass(), - sort_item_type_pass::mk_pass(), - markdown_index_pass::mk_pass(config), - page_pass::mk_pass(config.output_style), - markdown_pass::mk_pass( - markdown_writer::make_writer_factory(config) - ) - ]); - } -}