📝 docs: say what the comments now describe

Author: gaborbernat

common/src/layout.rs

@@ -257,10 +257,7 @@ fn space(width: usize) -> Padding<'static> {
     padding
 }
 
-/// The comments in a run, each with the spacing that preceded it, so a comment keeps the column an
-/// earlier alignment pass gave it.
-/// The comments in a run: the spacing that preceded each, its text, and whether a line break came
-/// first, which is what tells a comment of its own from one trailing the line before.
+/// The comments a run holds, in the order they were written.
 fn comments_of(padding: &Padding<'_>) -> Vec<String> {
     padding
         .parts()

common/src/nesting.rs

@@ -6,10 +6,11 @@
 
 use toml_doc::{Document, Entry, InlineTable, Key, KeyPart, Section, SectionKind, Value};
 
-/// Fold every `[name.sub]` into `[name]` as `sub.key` entries.
+/// Fold every `[name.sub]` into `[name]` as `sub.key` entries, and every `[[name.sub]]` into
+/// `sub = [ { ... } ]`.
 ///
-/// A repeated header, an array of tables, or a sub-table that still has tables of its own beneath
-/// it stays where it is, since none of those survive the move.
+/// A repeated header, or a sub-table that still has tables of its own beneath it, stays where it
+/// is: neither survives the move.
 pub fn collapse(document: &mut Document<'_>, name: &str) {
     collapse_where(document, name, &|_| true, usize::MAX);
 }

common/src/sections.rs

@@ -210,7 +210,7 @@ pub fn reorder_within(
             leaf.to_lowercase(),
         )
     });
-    // reordering breaks whatever spacing the file had, so every table starts one line apart; the
+    // reordering breaks whatever spacing the file had, so the tables land one line apart; the
     // spacing pass then widens or closes the gaps it cares about
     let opens_next: Vec<bool> = document
         .sections

common/src/strings.rs

@@ -89,7 +89,8 @@ fn form(text: &str, quoting: Quoting, unchanged: bool, wrap: Option<Wrap<'_>>) -
     if quoting.is_multiline() && text.contains('\n') {
         return Some(multiline_repr(&preserving_newlines(text)));
     }
-    // a newline written as an escape stays one; only a string already spread over lines keeps its
+    // a newline written as `\n` stays an escape; only a string already spread over lines keeps its
+    // breaks, which the branch above handles
     Some(Repr::basic_string(text))
 }