Document indent

Author: ratmice

lrpar/src/lib/ctbuilder.rs

@@ -1534,6 +1534,16 @@ where
     }
 }
 
+/// Indents a multi-line string and trims any trailing newline.
+/// This currently assumes that indentation on blank lines does not matter.
+///
+/// The algorithm used by this function is:
+/// 1. Prefix `s` with the indentation, indenting the first line.
+/// 2. Trim any trailing newlines.
+/// 3. Replace all newlines with `\n{indent}`` to indent all lines after the first.
+///
+/// It is plausible that we should a step 4, but currently do not:
+/// 4. Replace all `\n{indent}\n` with `\n\n`
 fn indent(s: &str, indent: &str) -> String {
     format!("{indent}{}\n", s.trim_end_matches('\n')).replace('\n', &format!("\n{}", indent))
 }

nimbleparse/src/main.rs

@@ -53,6 +53,16 @@ fn read_file<P: AsRef<Path>>(path: P) -> String {
     s
 }
 
+/// Indents a multi-line string and trims any trailing newline.
+/// This currently assumes that indentation on blank lines does not matter.
+///
+/// The algorithm used by this function is:
+/// 1. Prefix `s` with the indentation, indenting the first line.
+/// 2. Trim any trailing newlines.
+/// 3. Replace all newlines with `\n{indent}`` to indent all lines after the first.
+///
+/// It is plausible that we should a step 4, but currently do not:
+/// 4. Replace all `\n{indent}\n` with `\n\n`
 fn indent(s: &str, indent: &str) -> String {
     format!("{indent}{}\n", s.trim_end_matches('\n')).replace('\n', &format!("\n{}", indent))
 }