1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106

use std::sync::Arc;

use rustc_span::edition::Edition;

use crate::clean;
use crate::config::{RenderInfo, RenderOptions};
use crate::error::Error;
use crate::formats::cache::{Cache, CACHE_KEY};

/// Allows for different backends to rustdoc to be used with the `run_format()` function. Each
/// backend renderer has hooks for initialization, documenting an item, entering and exiting a
/// module, and cleanup/finalizing output.
crate trait FormatRenderer: Clone {
    /// Sets up any state required for the renderer. When this is called the cache has already been
    /// populated.
    fn init(
        krate: clean::Crate,
        options: RenderOptions,
        render_info: RenderInfo,
        edition: Edition,
        cache: &mut Cache,
    ) -> Result<(Self, clean::Crate), Error>;

    /// Renders a single non-module item. This means no recursive sub-item rendering is required.
    fn item(&mut self, item: clean::Item, cache: &Cache) -> Result<(), Error>;

    /// Renders a module (should not handle recursing into children).
    fn mod_item_in(
        &mut self,
        item: &clean::Item,
        item_name: &str,
        cache: &Cache,
    ) -> Result<(), Error>;

    /// Runs after recursively rendering all sub-items of a module.
    fn mod_item_out(&mut self, item_name: &str) -> Result<(), Error>;

    /// Post processing hook for cleanup and dumping output to files.
    fn after_krate(&mut self, krate: &clean::Crate, cache: &Cache) -> Result<(), Error>;

    /// Called after everything else to write out errors.
    fn after_run(&mut self, diag: &rustc_errors::Handler) -> Result<(), Error>;
}

/// Main method for rendering a crate.
crate fn run_format<T: FormatRenderer>(
    krate: clean::Crate,
    options: RenderOptions,
    render_info: RenderInfo,
    diag: &rustc_errors::Handler,
    edition: Edition,
) -> Result<(), Error> {
    let (krate, mut cache) = Cache::from_krate(
        render_info.clone(),
        options.document_private,
        &options.extern_html_root_urls,
        &options.output,
        krate,
    );

    let (mut format_renderer, mut krate) =
        T::init(krate, options, render_info, edition, &mut cache)?;

    let cache = Arc::new(cache);
    // Freeze the cache now that the index has been built. Put an Arc into TLS for future
    // parallelization opportunities
    CACHE_KEY.with(|v| *v.borrow_mut() = cache.clone());

    let mut item = match krate.module.take() {
        Some(i) => i,
        None => return Ok(()),
    };

    item.name = Some(krate.name.clone());

    // Render the crate documentation
    let mut work = vec![(format_renderer.clone(), item)];

    while let Some((mut cx, item)) = work.pop() {
        if item.is_mod() {
            // modules are special because they add a namespace. We also need to
            // recurse into the items of the module as well.
            let name = item.name.as_ref().unwrap().to_string();
            if name.is_empty() {
                panic!("Unexpected module with empty name");
            }

            cx.mod_item_in(&item, &name, &cache)?;
            let module = match item.kind {
                clean::StrippedItem(box clean::ModuleItem(m)) | clean::ModuleItem(m) => m,
                _ => unreachable!(),
            };
            for it in module.items {
                debug!("Adding {:?} to worklist", it.name);
                work.push((cx.clone(), it));
            }

            cx.mod_item_out(&name)?;
        } else if item.name.is_some() {
            cx.item(item, &cache)?;
        }
    }

    format_renderer.after_krate(&krate, &cache)?;
    format_renderer.after_run(diag)
}