src/librustdoc/formats/renderer.rs

   1 use rustc_middle::ty::TyCtxt;
   2 use rustc_span::Symbol;
   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 pub(crate) trait FormatRenderer<'tcx>: Sized {
  13     /// Gives a description of the renderer. Used for performance profiling.
  14     fn descr() -> &'static str;
  15
  16     /// Whether to call `item` recursively for modules
  17     ///
  18     /// This is true for html, and false for json. See #80664
  19     const RUN_ON_MODULE: bool;
  20
  21     /// Sets up any state required for the renderer. When this is called the cache has already been
  22     /// populated.
  23     fn init(
  24         krate: clean::Crate,
  25         options: RenderOptions,
  26         cache: Cache,
  27         tcx: TyCtxt<'tcx>,
  28     ) -> Result<(Self, clean::Crate), Error>;
  29
  30     /// Make a new renderer to render a child of the item currently being rendered.
  31     fn make_child_renderer(&self) -> Self;
  32
  33     /// Renders a single non-module item. This means no recursive sub-item rendering is required.
  34     fn item(&mut self, item: clean::Item) -> Result<(), Error>;
  35
  36     /// Renders a module (should not handle recursing into children).
  37     fn mod_item_in(&mut self, item: &clean::Item) -> Result<(), Error>;
  38
  39     /// Runs after recursively rendering all sub-items of a module.
  40     fn mod_item_out(&mut self) -> Result<(), Error> {
  41         Ok(())
  42     }
  43
  44     /// Post processing hook for cleanup and dumping output to files.
  45     fn after_krate(&mut self) -> Result<(), Error>;
  46
  47     fn cache(&self) -> &Cache;
  48 }
  49
  50 /// Main method for rendering a crate.
  51 pub(crate) fn run_format<'tcx, T: FormatRenderer<'tcx>>(
  52     krate: clean::Crate,
  53     options: RenderOptions,
  54     cache: Cache,
  55     tcx: TyCtxt<'tcx>,
  56 ) -> Result<(), Error> {
  57     let prof = &tcx.sess.prof;
  58
  59     let emit_crate = options.should_emit_crate();
  60     let (mut format_renderer, krate) = prof
  61         .verbose_generic_activity_with_arg("create_renderer", T::descr())
  62         .run(|| T::init(krate, options, cache, tcx))?;
  63
  64     if !emit_crate {
  65         return Ok(());
  66     }
  67
  68     // Render the crate documentation
  69     let mut work = vec![(format_renderer.make_child_renderer(), krate.module)];
  70
  71     let unknown = Symbol::intern("<unknown item>");
  72     while let Some((mut cx, item)) = work.pop() {
  73         if item.is_mod() && T::RUN_ON_MODULE {
  74             // modules are special because they add a namespace. We also need to
  75             // recurse into the items of the module as well.
  76             let _timer =
  77                 prof.generic_activity_with_arg("render_mod_item", item.name.unwrap().to_string());
  78
  79             cx.mod_item_in(&item)?;
  80             let (clean::StrippedItem(box clean::ModuleItem(module)) | clean::ModuleItem(module)) = *item.kind
  81             else { unreachable!() };
  82             for it in module.items {
  83                 debug!("Adding {:?} to worklist", it.name);
  84                 work.push((cx.make_child_renderer(), it));
  85             }
  86
  87             cx.mod_item_out()?;
  88         // FIXME: checking `item.name.is_some()` is very implicit and leads to lots of special
  89         // cases. Use an explicit match instead.
  90         } else if item.name.is_some() && !item.is_extern_crate() {
  91             prof.generic_activity_with_arg("render_item", item.name.unwrap_or(unknown).as_str())
  92                 .run(|| cx.item(item))?;
  93         }
  94     }
  95     prof.verbose_generic_activity_with_arg("renderer_after_krate", T::descr())
  96         .run(|| format_renderer.after_krate())
  97 }