From a5f5ee7fe7215696c9d2678a633b1d4499135516 Mon Sep 17 00:00:00 2001 From: Alexander Light Date: Sun, 9 Nov 2014 19:09:17 -0500 Subject: [PATCH] rustdoc: Allow private modules be included in docs Added a --all-modules/-a flag which causes rustdoc to include documentation information even for modules which are not visible outside of the crate they are defined in. This flag is off by default. It is most useful if the strip-private pass is disable but can be useful even without this. There is no change in rustdoc's output with this flag off. --- src/librustdoc/html/render.rs | 84 +++++++++++++++++++---------------- src/librustdoc/lib.rs | 6 ++- src/librustdoc/visit_ast.rs | 3 -- 3 files changed, 51 insertions(+), 42 deletions(-) diff --git a/src/librustdoc/html/render.rs b/src/librustdoc/html/render.rs index fbd2611acb92d..b115f25c5d3f3 100644 --- a/src/librustdoc/html/render.rs +++ b/src/librustdoc/html/render.rs @@ -100,6 +100,10 @@ pub struct Context { /// real location of an item. This is used to allow external links to /// publicly reused items to redirect to the right location. pub render_redirect_pages: bool, + /// A flag, which when turned on, will include the documentation of all + /// referenced modules in the crate, even those that are not visible outside + /// the crate. + pub include_priv: bool, } /// Indicates where an external crate can be found. @@ -235,9 +239,13 @@ local_data_key!(pub cache_key: Arc) local_data_key!(pub current_location_key: Vec ) /// Generates the documentation for `crate` into the directory `dst` -pub fn run(mut krate: clean::Crate, external_html: &ExternalHtml, dst: Path) -> io::IoResult<()> { +pub fn run(mut krate: clean::Crate, + external_html: &ExternalHtml, + dst: Path, + privs: bool) -> io::IoResult<()> { let mut cx = Context { dst: dst, + include_priv: privs, current: Vec::new(), root_path: String::new(), sidebar: HashMap::new(), @@ -1193,7 +1201,7 @@ impl Context { // these modules are recursed into, but not rendered normally (a // flag on the context). if !self.render_redirect_pages { - self.render_redirect_pages = ignore_private_item(&item); + self.render_redirect_pages = self.ignore_private_item(&item); } match item.inner { @@ -1212,7 +1220,7 @@ impl Context { clean::ModuleItem(m) => m, _ => unreachable!() }; - this.sidebar = build_sidebar(&m); + this.sidebar = this.build_sidebar(&m); for item in m.items.into_iter() { f(this,item); } @@ -1231,6 +1239,40 @@ impl Context { _ => Ok(()) } } + + fn build_sidebar(&self, m: &clean::Module) -> HashMap> { + let mut map = HashMap::new(); + for item in m.items.iter() { + if self.ignore_private_item(item) { continue } + + let short = shortty(item).to_static_str(); + let myname = match item.name { + None => continue, + Some(ref s) => s.to_string(), + }; + let v = match map.entry(short.to_string()) { + Vacant(entry) => entry.set(Vec::with_capacity(1)), + Occupied(entry) => entry.into_mut(), + }; + v.push(myname); + } + + for (_, items) in map.iter_mut() { + items.as_mut_slice().sort(); + } + return map; + } + + fn ignore_private_item(&self, it: &clean::Item) -> bool { + match it.inner { + clean::ModuleItem(ref m) => { + (m.items.len() == 0 && it.doc_value().is_none()) || + (!self.include_priv && it.visibility != Some(ast::Public)) + } + clean::PrimitiveItem(..) => it.visibility != Some(ast::Public), + _ => false, + } + } } impl<'a> Item<'a> { @@ -1444,7 +1486,7 @@ fn item_module(w: &mut fmt::Formatter, cx: &Context, try!(document(w, item)); let mut indices = range(0, items.len()).filter(|i| { - !ignore_private_item(&items[*i]) + !cx.ignore_private_item(&items[*i]) }).collect::>(); fn cmp(i1: &clean::Item, i2: &clean::Item, idx1: uint, idx2: uint) -> Ordering { @@ -2158,29 +2200,6 @@ impl<'a> fmt::Show for Sidebar<'a> { } } -fn build_sidebar(m: &clean::Module) -> HashMap> { - let mut map = HashMap::new(); - for item in m.items.iter() { - if ignore_private_item(item) { continue } - - let short = shortty(item).to_static_str(); - let myname = match item.name { - None => continue, - Some(ref s) => s.to_string(), - }; - let v = match map.entry(short.to_string()) { - Vacant(entry) => entry.set(Vec::with_capacity(1)), - Occupied(entry) => entry.into_mut(), - }; - v.push(myname); - } - - for (_, items) in map.iter_mut() { - items.as_mut_slice().sort(); - } - return map; -} - impl<'a> fmt::Show for Source<'a> { fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result { let Source(s) = *self; @@ -2215,17 +2234,6 @@ fn item_primitive(w: &mut fmt::Formatter, render_methods(w, it) } -fn ignore_private_item(it: &clean::Item) -> bool { - match it.inner { - clean::ModuleItem(ref m) => { - (m.items.len() == 0 && it.doc_value().is_none()) || - it.visibility != Some(ast::Public) - } - clean::PrimitiveItem(..) => it.visibility != Some(ast::Public), - _ => false, - } -} - fn get_basic_keywords() -> &'static str { "rust, rustlang, rust-lang" } diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs index 5e2f56e00fc0d..c23d6341eab06 100644 --- a/src/librustdoc/lib.rs +++ b/src/librustdoc/lib.rs @@ -114,6 +114,8 @@ pub fn opts() -> Vec { optmulti("", "plugins", "space separated list of plugins to also load", "PLUGINS"), optflag("", "no-defaults", "don't run the default passes"), + optflag("a", "all-modules", "Include documentation from all modules, including those not \ + visible externally"), optflag("", "test", "run code examples as tests"), optmulti("", "test-args", "arguments to pass to the test runner", "ARGS"), @@ -206,6 +208,7 @@ pub fn main_args(args: &[String]) -> int { let output = matches.opt_str("o").map(|s| Path::new(s)); let cfgs = matches.opt_strs("cfg"); + let inc_priv = matches.opt_present("a") || matches.opt_present("all-modules"); let external_html = match ExternalHtml::load( matches.opt_strs("html-in-header").as_slice(), @@ -241,7 +244,8 @@ pub fn main_args(args: &[String]) -> int { let started = time::precise_time_ns(); match matches.opt_str("w").as_ref().map(|s| s.as_slice()) { Some("html") | None => { - match html::render::run(krate, &external_html, output.unwrap_or(Path::new("doc"))) { + match html::render::run(krate, &external_html, output.unwrap_or(Path::new("doc")), + inc_priv) { Ok(()) => {} Err(e) => panic!("failed to generate documentation: {}", e), } diff --git a/src/librustdoc/visit_ast.rs b/src/librustdoc/visit_ast.rs index 1cafc38f826c9..d1acd46315e27 100644 --- a/src/librustdoc/visit_ast.rs +++ b/src/librustdoc/visit_ast.rs @@ -158,9 +158,6 @@ impl<'a, 'tcx> RustdocVisitor<'a, 'tcx> { } pub fn visit_view_item(&mut self, item: &ast::ViewItem, om: &mut Module) { - if item.vis != ast::Public { - return om.view_items.push(item.clone()); - } let please_inline = item.attrs.iter().any(|item| { match item.meta_item_list() { Some(list) => {