Add comments

More housekeeping to make the codebase more understandable.

2 files changed, 10 insertions, 1 deletions

diff --git a/src/generate_html.rs b/src/generate_html.rs
index 7bec912..b635767 100644
--- a/src/generate_html.rs
+++ b/src/generate_html.rs
@@ -6,8 +6,11 @@ use recipe::*;
 
 pub fn generate_html(page: &Page, website: &Website) -> String {
     let root = page.root();
+
+    // Get page name as a plain string and as an HTML fragment.
     let mut page_name_plain = page.name.clone();
     let mut page_name_html = sanitize_text(&page_name_plain, true);
+    // Find any override-title fragments.
     for block in &page.document.blocks {
         if let Block::Fragment { language, content } = block {
             if language == "override-title" {
@@ -17,8 +20,10 @@ pub fn generate_html(page: &Page, website: &Website) -> String {
             }
         }
     }
-    let site_name = sanitize_text(&website.name, true);
     page_name_plain = sanitize_text(&page_name_plain, true);
+
+    // Get the URL of the parent page.
+    let site_name = sanitize_text(&website.name, true);
     let mut parent_url = String::new();
     for segment in &page.parents {
         parent_url.push_str(&make_url_safe(segment)); parent_url.push('/');
@@ -31,6 +36,8 @@ pub fn generate_html(page: &Page, website: &Website) -> String {
         Some(name) => format!("<a id='parent' href='../{}.html'>{name}</a>", make_url_safe(name)),
         None => String::new(),
     };
+
+    // Format tables of contents and the main page.
     let toc = get_table_of_contents(page);
     let toc_main = if page.headings.len() >= 3 {
         format!("<details><summary></summary>\n{toc}</details>\n")
diff --git a/src/main.rs b/src/main.rs
index 14a1f79..33fe16d 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -166,6 +166,7 @@ pub fn write_file(text: &str, destination: &PathBuf, ext: &str, last_modified: O
     }
 }
 
+// Turn a string into a tidy URL slug.
 pub fn make_url_safe(text: &str) -> String {
     text.to_ascii_lowercase().chars().filter_map(|c|
         if c.is_alphanumeric() || "-_~.+/#".contains(c) { Some(c) }
@@ -174,6 +175,7 @@ pub fn make_url_safe(text: &str) -> String {
     .collect()
 }
 
+// Prevent link hrefs from breaking out of quotations.
 pub fn url_encode(text: &str) -> String {
     let mut output = String::new();
     for c in text.chars() {