rustdoc/formats/
renderer.rs

1use rustc_data_structures::profiling::SelfProfilerRef;
2use rustc_middle::ty::TyCtxt;
3
4use crate::clean;
5use crate::config::{EmitType, RenderOptions};
6use crate::error::Error;
7use 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.
12pub(crate) trait FormatRenderer<'tcx>: Sized {
13    /// A description of the renderer. Used for performance profiling.
14    const DESCR: &'static str;
15
16    /// Whether to call `item` recursively for modules.
17    ///
18    /// See [#80664](https://github.com/rust-lang/rust/issues/80664).
19    const RUN_ON_MODULE: bool;
20
21    const NON_STATIC_FILE_EMIT_TYPE: EmitType;
22
23    /// This associated type is the type where the current module information is stored.
24    ///
25    /// For each module, we go through their items by calling for each item:
26    ///
27    /// 1. `save_module_data`
28    /// 2. `item`
29    /// 3. `restore_module_data`
30    ///
31    /// This is because the `item` method might update information in `self` (for example if the child
32    /// is a module). To prevent it from impacting the other children of the current module, we need to
33    /// reset the information between each call to `item` by using `restore_module_data`.
34    type ModuleData;
35
36    /// This method is called right before call [`Self::item`]. This method returns a type
37    /// containing information that needs to be reset after the [`Self::item`] method has been
38    /// called with the [`Self::restore_module_data`] method.
39    ///
40    /// In short it goes like this:
41    ///
42    /// ```ignore (not valid code)
43    /// let reset_data = renderer.save_module_data();
44    /// renderer.item(item)?;
45    /// renderer.restore_module_data(reset_data);
46    /// ```
47    fn save_module_data(&mut self) -> Self::ModuleData;
48    /// Used to reset current module's information.
49    fn restore_module_data(&mut self, info: Self::ModuleData);
50
51    /// Renders a single non-module item. This means no recursive sub-item rendering is required.
52    fn item(&mut self, item: &clean::Item) -> Result<(), Error>;
53
54    /// Renders a module (should not handle recursing into children).
55    fn mod_item_in(&mut self, item: &clean::Item) -> Result<(), Error>;
56
57    /// Runs after recursively rendering all sub-items of a module.
58    fn mod_item_out(&mut self) -> Result<(), Error> {
59        Ok(())
60    }
61
62    /// Post processing hook for cleanup and dumping output to files.
63    fn after_krate(self) -> Result<(), Error>;
64}
65
66fn run_format_inner<'tcx, T: FormatRenderer<'tcx>>(
67    cx: &mut T,
68    item: &clean::Item,
69    prof: &SelfProfilerRef,
70) -> Result<(), Error> {
71    if item.is_mod() && T::RUN_ON_MODULE {
72        // modules are special because they add a namespace. We also need to
73        // recurse into the items of the module as well.
74        let _timer =
75            prof.generic_activity_with_arg("render_mod_item", item.name.unwrap().to_string());
76
77        cx.mod_item_in(item)?;
78        let (clean::StrippedItem(clean::ModuleItem(ref module)) | clean::ModuleItem(ref module)) =
79            item.inner.kind
80        else {
81            unreachable!()
82        };
83        for it in module.items.iter() {
84            let info = cx.save_module_data();
85            run_format_inner(cx, it, prof)?;
86            cx.restore_module_data(info);
87        }
88
89        cx.mod_item_out()?;
90    // FIXME: checking `item.name.is_some()` is very implicit and leads to lots of special
91    // cases. Use an explicit match instead.
92    } else if let Some(item_name) = item.name
93        && !item.is_extern_crate()
94    {
95        prof.generic_activity_with_arg("render_item", item_name.as_str()).run(|| cx.item(item))?;
96    }
97    Ok(())
98}
99
100/// Main method for rendering a crate.
101pub(crate) fn run_format<
102    'tcx,
103    T: FormatRenderer<'tcx>,
104    F: FnOnce(clean::Crate, RenderOptions, Cache, TyCtxt<'tcx>) -> Result<(T, clean::Crate), Error>,
105>(
106    krate: clean::Crate,
107    options: RenderOptions,
108    cache: Cache,
109    tcx: TyCtxt<'tcx>,
110    init: F,
111) -> Result<(), Error> {
112    let prof = &tcx.sess.prof;
113
114    let emit_non_static_files = options.emit.contains(&T::NON_STATIC_FILE_EMIT_TYPE);
115    let (mut format_renderer, krate) = prof
116        .verbose_generic_activity_with_arg("create_renderer", T::DESCR)
117        .run(|| init(krate, options, cache, tcx))?;
118
119    if !emit_non_static_files {
120        return Ok(());
121    }
122
123    // Render the crate documentation
124    run_format_inner(&mut format_renderer, &krate.module, prof)?;
125
126    prof.verbose_generic_activity_with_arg("renderer_after_krate", T::DESCR)
127        .run(|| format_renderer.after_krate())
128}
rustdoc/formats/renderer.rs

rustdoc/formats/
renderer.rs
