Add comments; #1

src/lib.rs

@@ -198,6 +198,8 @@ impl Document {
         Ok(())
     }
 
+    /// Write the top-level chapters. These need special treatment so that they get created even
+    /// if they're completely empty, in order not to break include directives.
     fn write_chapters(modules: &[Module], summary: &str, generated_dir: &Path) -> Result<()> {
         for chapter in modules {
             let out_file = generated_dir.join(&chapter.file_name());
@@ -225,6 +227,7 @@ impl Document {
         Ok(())
     }
 
+    /// Write modules for all sub-sections recursively. Only create files if they have some content.
     fn write_modules(modules: &[Module], summary: &str, generated_dir: &Path) -> Result<()> {
         for module in modules {
             if let Module::WithContent {

src/templating.rs

@@ -59,11 +59,14 @@ pub enum DocumentVariant {
 /// The representation of a module, before being finally rendered.
 #[derive(Clone, Debug, PartialEq)]
 pub enum Module {
+    /// This is the full version of a module.
     WithContent {
         file_name: String,
         text: String,
         included_modules: Option<Vec<Self>>,
     },
+    /// This is an outline of a module that only carries its file name.
+    /// Its purpose is to create blank assemblies for top-level chapters.
     Blank {
         file_name: String,
     },
@@ -74,12 +77,14 @@ impl Module {
     pub fn include_statement(&self) -> String {
         format!("include::{}[leveloffset=+1]", self.file_name())
     }
+    /// The module's file name.
     pub fn file_name(&self) -> &str {
         match self {
             Self::WithContent { file_name, .. } => file_name,
             Self::Blank { file_name, .. } => file_name,
         }
     }
+    /// Return `true` if the module is of the `WithContent` variant.
     fn has_content(&self) -> bool {
         match self {
             Self::WithContent { .. } => true,