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.
descr() -> &'static str14 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.
init( krate: clean::Crate, options: RenderOptions, cache: Cache, tcx: TyCtxt<'tcx>, ) -> Result<(Self, clean::Crate), Error>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.
make_child_renderer(&self) -> Self31 fn make_child_renderer(&self) -> Self;
32
33 /// Renders a single non-module item. This means no recursive sub-item rendering is required.
item(&mut self, item: clean::Item) -> Result<(), Error>34 fn item(&mut self, item: clean::Item) -> Result<(), Error>;
35
36 /// Renders a module (should not handle recursing into children).
mod_item_in(&mut self, item: &clean::Item) -> Result<(), Error>37 fn mod_item_in(&mut self, item: &clean::Item) -> Result<(), Error>;
38
39 /// Runs after recursively rendering all sub-items of a module.
mod_item_out(&mut self) -> Result<(), Error>40 fn mod_item_out(&mut self) -> Result<(), Error> {
41 Ok(())
42 }
43
44 /// Post processing hook for cleanup and dumping output to files.
after_krate(&mut self) -> Result<(), Error>45 fn after_krate(&mut self) -> Result<(), Error>;
46
cache(&self) -> &Cache47 fn cache(&self) -> &Cache;
48 }
49
50 /// Main method for rendering a crate.
run_format<'tcx, T: FormatRenderer<'tcx>>( krate: clean::Crate, options: RenderOptions, cache: Cache, tcx: TyCtxt<'tcx>, ) -> Result<(), Error>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 }
98