src/librustdoc/formats/renderer.rs

   1 use rustc_middle::ty::TyCtxt;
   2 use rustc_span::edition::Edition;
   3
   4 use crate::clean;
   5 use crate::config::RenderOptions;
   6 use crate::error::Error;
   7 use crate::formats::cache::Cache;
   8
   9 /// Allows for different backends to rustdoc to be used with the `run_format()` function. Each
  10 /// backend renderer has hooks for initialization, documenting an item, entering and exiting a
  11 /// module, and cleanup/finalizing output.
  12 crate trait FormatRenderer<'tcx>: Sized {
  13     /// Gives a description of the renderer. Used for performance profiling.
  14     fn descr() -> &'static str;
  15
  16     /// Sets up any state required for the renderer. When this is called the cache has already been
  17     /// populated.
  18     fn init(
  19         krate: clean::Crate,
  20         options: RenderOptions,
  21         edition: Edition,
  22         cache: Cache,
  23         tcx: TyCtxt<'tcx>,
  24     ) -> Result<(Self, clean::Crate), Error>;
  25
  26     /// Make a new renderer to render a child of the item currently being rendered.
  27     fn make_child_renderer(&self) -> Self;
  28
  29     /// Renders a single non-module item. This means no recursive sub-item rendering is required.
  30     fn item(&mut self, item: clean::Item) -> Result<(), Error>;
  31
  32     /// Renders a module (should not handle recursing into children).
  33     fn mod_item_in(&mut self, item: &clean::Item, item_name: &str) -> Result<(), Error>;
  34
  35     /// Runs after recursively rendering all sub-items of a module.
  36     fn mod_item_out(&mut self, item_name: &str) -> Result<(), Error>;
  37
  38     /// Post processing hook for cleanup and dumping output to files.
  39     ///
  40     /// A handler is available if the renderer wants to report errors.
  41     fn after_krate(
  42         &mut self,
  43         krate: &clean::Crate,
  44         diag: &rustc_errors::Handler,
  45     ) -> Result<(), Error>;
  46
  47     fn cache(&self) -> &Cache;
  48 }
  49
  50 /// Main method for rendering a crate.
  51 crate fn run_format<'tcx, T: FormatRenderer<'tcx>>(
  52     krate: clean::Crate,
  53     options: RenderOptions,
  54     cache: Cache,
  55     diag: &rustc_errors::Handler,
  56     edition: Edition,
  57     tcx: TyCtxt<'tcx>,
  58 ) -> Result<(), Error> {
  59     let prof = &tcx.sess.prof;
  60
  61     let (mut format_renderer, mut krate) = prof
  62         .extra_verbose_generic_activity("create_renderer", T::descr())
  63         .run(|| T::init(krate, options, edition, cache, tcx))?;
  64
  65     let mut item = match krate.module.take() {
  66         Some(i) => i,
  67         None => return Ok(()),
  68     };
  69
  70     item.name = Some(krate.name);
  71
  72     // Render the crate documentation
  73     let mut work = vec![(format_renderer.make_child_renderer(), item)];
  74
  75     let unknown = rustc_span::Symbol::intern("<unknown item>");
  76     while let Some((mut cx, item)) = work.pop() {
  77         if item.is_mod() {
  78             // modules are special because they add a namespace. We also need to
  79             // recurse into the items of the module as well.
  80             let name = item.name.as_ref().unwrap().to_string();
  81             if name.is_empty() {
  82                 panic!("Unexpected module with empty name");
  83             }
  84             let _timer = prof.generic_activity_with_arg("render_mod_item", name.as_str());
  85
  86             cx.mod_item_in(&item, &name)?;
  87             let module = match *item.kind {
  88                 clean::StrippedItem(box clean::ModuleItem(m)) | clean::ModuleItem(m) => m,
  89                 _ => unreachable!(),
  90             };
  91             for it in module.items {
  92                 debug!("Adding {:?} to worklist", it.name);
  93                 work.push((cx.make_child_renderer(), it));
  94             }
  95
  96             cx.mod_item_out(&name)?;
  97         // FIXME: checking `item.name.is_some()` is very implicit and leads to lots of special
  98         // cases. Use an explicit match instead.
  99         } else if item.name.is_some() && !item.is_extern_crate() {
 100             prof.generic_activity_with_arg("render_item", &*item.name.unwrap_or(unknown).as_str())
 101                 .run(|| cx.item(item))?;
 102         }
 103     }
 104     prof.extra_verbose_generic_activity("renderer_after_krate", T::descr())
 105         .run(|| format_renderer.after_krate(&krate, diag))
 106 }