Add comments to ease readability and maintainability

src/normal_diff.rs

@@ -111,6 +111,8 @@ fn make_diff(expected: &[u8], actual: &[u8]) -> Vec<Mismatch> {
 
 #[must_use]
 pub fn diff(expected: &[u8], actual: &[u8]) -> Vec<u8> {
+    // See https://www.gnu.org/software/diffutils/manual/html_node/Detailed-Normal.html
+    // for details on the syntax of the normal format.
     let mut output = Vec::new();
     let diff_results = make_diff(expected, actual);
     for result in diff_results {
@@ -121,6 +123,7 @@ pub fn diff(expected: &[u8], actual: &[u8]) -> Vec<u8> {
         match (expected_count, actual_count) {
             (0, 0) => unreachable!(),
             (0, _) => writeln!(
+                // 'a' stands for "Add lines"
                 &mut output,
                 "{}a{},{}",
                 line_number_expected - 1,
@@ -129,6 +132,7 @@ pub fn diff(expected: &[u8], actual: &[u8]) -> Vec<u8> {
             )
             .unwrap(),
             (_, 0) => writeln!(
+                // 'd' stands for "Delete lines"
                 &mut output,
                 "{},{}d{}",
                 line_number_expected,
@@ -137,12 +141,16 @@ pub fn diff(expected: &[u8], actual: &[u8]) -> Vec<u8> {
             )
             .unwrap(),
             (1, 1) => writeln!(
+                // 'c' stands for "Change lines"
+                // exactly one line replaced by one line
                 &mut output,
                 "{}c{}",
-                line_number_expected, line_number_actual
+                line_number_expected,
+                line_number_actual
             )
             .unwrap(),
             (1, _) => writeln!(
+                // one line replaced by multiple lines
                 &mut output,
                 "{}c{},{}",
                 line_number_expected,
@@ -151,6 +159,7 @@ pub fn diff(expected: &[u8], actual: &[u8]) -> Vec<u8> {
             )
             .unwrap(),
             (_, 1) => writeln!(
+                // multiple lines replaced by one line
                 &mut output,
                 "{},{}c{}",
                 line_number_expected,
@@ -159,6 +168,7 @@ pub fn diff(expected: &[u8], actual: &[u8]) -> Vec<u8> {
             )
             .unwrap(),
             _ => writeln!(
+                // general case: multiple lines replaced by multiple lines
                 &mut output,
                 "{},{}c{},{}",
                 line_number_expected,