Add comments

Author: sakex

mdbook-tera-backend/src/main.rs

@@ -16,7 +16,7 @@ fn main() {
         .unwrap();
 
     let tera_template = config
-        .create_template_and_components(&ctx.root)
+        .create_template(&ctx.root)
         .expect("Failed to create components");
 
     let mut renderer = Renderer::new(ctx, tera_template).expect("Failed to create renderer");

mdbook-tera-backend/src/tera_renderer/custom_component.rs

@@ -11,6 +11,7 @@ pub struct TeraRendererConfig {
 }
 
 impl TeraRendererConfig {
+    /// Recursively add all templates in the `templates_dir` to the `tera_template`.
     fn add_templates_recursively(tera_template: &mut Tera, directory: &Path) -> Result<()> {
         for entry in std::fs::read_dir(directory)? {
             let entry = entry?;
@@ -24,7 +25,8 @@ impl TeraRendererConfig {
         Ok(())
     }
 
-    pub fn create_template_and_components(&self, current_dir: &Path) -> Result<Tera> {
+    /// Create the `tera_template` and add all templates in the `templates_dir` to it.
+    pub fn create_template(&self, current_dir: &Path) -> Result<Tera> {
         let mut tera_template = Tera::default();
         Self::add_templates_recursively(
             &mut tera_template,

mdbook-tera-backend/src/tera_renderer/renderer.rs

@@ -8,6 +8,27 @@ use std::path::Path;
 use std::sync::Arc;
 use tera::Tera;
 
+/// Renderer for the tera backend.
+///
+/// This will read all the files in the `RenderContext` and render them using the `Tera` template.
+///
+/// # Example
+///
+/// ```
+/// let mut stdin = io::stdin();
+/// let ctx = RenderContext::from_json(&mut stdin).unwrap();
+/// let config: TeraRendererConfig = ctx
+///     .config
+///     .get_deserialized_opt("output.tera-backend")
+///     .expect("Failed to get tera-backend config")
+///     .unwrap();
+///
+/// let tera_template = config
+///    .create_template(&ctx.root)
+///    .expect("Failed to create components");
+/// let mut renderer = Renderer::new(ctx, tera_template).expect("Failed to create renderer");
+/// renderer.render_book().expect("Failed to render book");
+/// ```
 pub(crate) struct Renderer {
     ctx: Arc<RenderContext>,
     serialized_ctx: serde_json::Value,
@@ -16,6 +37,12 @@ pub(crate) struct Renderer {
 }
 
 impl Renderer {
+    /// Create a new `Renderer` from the `RenderContext` and `Tera` template.
+    ///
+    /// # Arguments
+    ///
+    /// `ctx`: The `RenderContext` to be used for rendering. This is usually obtained from `stdin`.
+    /// `tera_template`: A pre-configured `Tera` template.
     pub(crate) fn new(ctx: RenderContext, tera_template: Tera) -> Result<Renderer> {
         let mut renderer = Renderer {
             serialized_ctx: serde_json::to_value(&ctx)?,
@@ -29,6 +56,16 @@ impl Renderer {
         Ok(renderer)
     }
 
+    /// Render the book.
+    pub(crate) fn render_book(&mut self) -> Result<()> {
+        let dest_dir = self.ctx.destination.parent().unwrap().to_owned();
+        if !dest_dir.is_dir() {
+            return Err(anyhow!("{dest_dir:?} is not a directory"));
+        }
+        self.render_book_directory(&dest_dir)
+    }
+
+    /// Create the `get_context` function for the `Tera` template, a helper that allows retrieving values from `ctx`.
     fn create_get_context_function(&self) -> impl tera::Function {
         let ctx_rc = Arc::clone(&self.ctx);
         move |args: &HashMap<String, serde_json::value::Value>| -> tera::Result<tera::Value> {
@@ -48,14 +85,7 @@ impl Renderer {
         }
     }
 
-    pub(crate) fn render_book(&mut self) -> Result<()> {
-        let dest_dir = self.ctx.destination.parent().unwrap().to_owned();
-        if !dest_dir.is_dir() {
-            return Err(anyhow!("{dest_dir:?} is not a directory"));
-        }
-        self.render_book_directory(&dest_dir)
-    }
-
+    /// Render the book directory located at `path` recursively.
     fn render_book_directory(&mut self, path: &Path) -> Result<()> {
         for entry in path.read_dir()? {
             let entry = entry?;
@@ -69,17 +99,23 @@ impl Renderer {
         Ok(())
     }
 
+    /// Reads the file at `path` and renders it.
     fn process_file(&mut self, path: &Path) -> Result<()> {
         if path.extension().unwrap_or_default() != "html" {
             return Ok(());
         }
         let file_content = std::fs::read_to_string(path)?;
-        let output = self.render(&file_content, path)?;
+        let output = self.render_file_content(&file_content, path)?;
         let mut output_file = fs::File::create(path)?;
         output_file.write_all(output.as_bytes())?;
         Ok(())
     }
 
+    /// Creates the rendering context to be passed to the templates.
+    ///
+    /// # Arguments
+    ///
+    /// `path`: The path to the file that will be added as extra context to the renderer.
     fn create_context(&mut self, path: &Path) -> tera::Context {
         let mut context = tera::Context::new();
         context.insert("path", path);
@@ -92,7 +128,17 @@ impl Renderer {
         context
     }
 
-    fn render(&mut self, file_content: &str, path: &Path) -> Result<String> {
+    /// Rendering logic for an individual file.
+    ///
+    /// # Arguments
+    ///
+    /// `file_content`: The content of the file to be rendered.
+    /// `path`: The path of the file to be rendered.
+    ///
+    /// # Returns
+    ///
+    /// The rendered file.
+    fn render_file_content(&mut self, file_content: &str, path: &Path) -> Result<String> {
         let tera_context = self.create_context(path);
 
         let rendered_file = self