Document all the things

Author: oli-obk

src/diff.rs

@@ -24,24 +24,32 @@ impl<'a> DiffState<'a> {
             eprintln!(" {line}");
         }
     }
+
     fn print_skipped_msg(&self, skipped: usize) {
         match skipped {
+            // When the amount of skipped lines is exactly `CONTEXT * 2`, we already
+            // print all the context and don't actually skip anything.
             0 => {}
+            // Instead of writing a line saying we skipped one line, print that one line
             1 => eprintln!(" {}", self.skipped_lines[CONTEXT]),
             _ => eprintln!("... {skipped} lines skipped ..."),
         }
     }
+
+    /// Print an initial `CONTEXT` amount of lines.
     fn print_start_skip(&self) {
         for line in self.skipped_lines.iter().take(CONTEXT) {
             eprintln!(" {line}");
         }
     }
+
     fn print_skip(&mut self) {
         let half = self.skipped_lines.len() / 2;
         if !self.print_start_context {
             self.print_start_context = true;
             self.print_end_skip(self.skipped_lines.len().saturating_sub(CONTEXT));
         } else if half < CONTEXT {
+            // Print all the skipped lines if the amount of context desired is less than the amount of lines
             for line in self.skipped_lines.drain(..) {
                 eprintln!(" {line}");
             }
@@ -83,8 +91,9 @@ impl<'a> DiffState<'a> {
                 self.skip(l);
             }
             Right(r) => {
+                // When there's an added line after a removed line, we'll want to special case some print cases.
+                // FIXME(oli-obk): also do special printing modes when there are multiple lines that only have minor changes.
                 if let Some(l) = self.prev_left.take() {
-                    // If the lines only add chars or only remove chars, display an inline diff
                     let diff = chars(l, r);
                     let mut seen_l = false;
                     let mut seen_r = false;
@@ -96,7 +105,8 @@ impl<'a> DiffState<'a> {
                         }
                     }
                     if seen_l && seen_r {
-                        // the line both adds and removes chars, print both lines, but highlight their differences
+                        // The line both adds and removes chars, print both lines, but highlight their differences instead of
+                        // drawing the entire line in red/green.
                         eprint!("{}", "-".red());
                         for char in &diff {
                             match char {
@@ -116,6 +126,7 @@ impl<'a> DiffState<'a> {
                         }
                         eprintln!();
                     } else {
+                        // The line only adds or only removes chars, print a single line highlighting their differences.
                         eprint!("{}", "~".yellow());
                         for char in diff {
                             match char {