Expand and improve docstrings

src/context.rs

@@ -1,10 +1,17 @@
+//! Calculate which nearby lines should also be displayed.
+
 use std::collections::{HashMap, HashSet};
 
 use crate::{
     lines::LineNumber,
     syntax::{zip_repeat_shorter, MatchKind, MatchedPos},
 };
 
+/// The maximum number of lines that may be displayed above and below
+/// the modified lines.
+///
+/// We may show fewer lines if the modified lines are at the beginning
+/// or end of the file.
 const MAX_PADDING: usize = 3;
 
 pub fn opposite_positions(mps: &[MatchedPos]) -> HashMap<LineNumber, HashSet<LineNumber>> {
@@ -43,14 +50,20 @@ pub fn opposite_positions(mps: &[MatchedPos]) -> HashMap<LineNumber, HashSet<Lin
 }
 
 /// Before:
+///
+/// ```text
 /// 118    --
 /// 119    --
 /// 120    -- (novel)
+/// ```
 ///
 /// After:
+///
+/// ```text
 /// 118    88 (expanded from closest)
 /// 119    89 (closest match)
 /// 120    -- (novel)
+/// ```
 fn before_with_opposites(
     before_lines: &[LineNumber],
     opposite_lines: &HashMap<LineNumber, HashSet<LineNumber>>,

src/hunks.rs

@@ -1,3 +1,8 @@
+//! Calculating which modified lines should be displayed together.
+
+/// The maximum number of lines that may occur between changed lines in a hunk.
+///
+/// If we exceed this, the lines are stored in separate hunks.
 const MAX_DISTANCE: usize = 4;
 
 use std::collections::{HashMap, HashSet};
@@ -8,6 +13,8 @@ use crate::{
     syntax::{zip_pad_shorter, MatchedPos},
 };
 
+/// A hunk represents a series of modified lines that are displayed
+/// together.
 #[derive(Debug, Clone)]
 pub struct Hunk {
     pub lines: Vec<(Option<LineNumber>, Option<LineNumber>)>,
@@ -402,18 +409,21 @@ pub fn matched_pos_to_hunks(lhs_mps: &[MatchedPos], rhs_mps: &[MatchedPos]) -> V
 ///
 /// Before:
 ///
+/// ```text
 /// 1 11
 /// 3 14
 /// 4 --
+/// ```
 ///
-/// After
+/// After:
 ///
+/// ```text
 /// 1 10
 /// 2 12 (choosing to align even though content doesn't match)
 /// - 13 (fix uneven gap)
 /// 3 14
 /// 4 -- (preserve outer gaps)
-///
+/// ```
 fn ensure_contiguous(
     lines: &[(Option<LineNumber>, Option<LineNumber>)],
 ) -> Vec<(Option<LineNumber>, Option<LineNumber>)> {

src/lines.rs

@@ -7,6 +7,8 @@ use std::{cmp::max, fmt};
 
 /// A distinct number type for line numbers, to prevent confusion with
 /// other numerical data.
+///
+/// Zero-indexed internally.
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct LineNumber(pub usize);
 

src/style.rs

@@ -35,7 +35,12 @@ impl Style {
     }
 }
 
-/// "fooba", 3 -> vec!["foo", "ba "]
+/// Split a string into equal length parts, padding the last part if
+/// necessary.
+///
+/// ```
+/// split_string("fooba", 3) // vec!["foo", "ba "]
+/// ```
 fn split_string(s: &str, max_len: usize) -> Vec<String> {
     let mut res = vec![];
     let mut s = s;

src/tree_sitter_parser.rs

@@ -1,4 +1,4 @@
-//! Parse code with tree-sitter language implementations.
+//! Load and configure parsers written with tree-sitter.
 
 use std::{borrow::Borrow, collections::HashSet, ffi::OsStr};
 
@@ -10,21 +10,34 @@ use crate::{
     syntax::{AtomKind, Syntax},
 };
 
+/// Configuration for a tree-sitter parser.
 pub struct TreeSitterConfig {
+    /// The language name shown to the user.
     pub name: &'static str,
+
+    /// The tree-sitter language parser.
     pub language: Language,
-    // Tree-sitter nodes that we treat as indivisible atoms. This is
-    // particularly useful for strings, as some grammars use several
-    // nodes for a single string literal. We don't want to say
-    // e.g. the closing string delimiter moved, as it's confusing and
-    // not well-balanced syntax.
-    //
-    // This is also useful for when tree-sitter nodes don't include
-    // all the children in the source. This is known limitation of
-    // tree-sitter, and occurs more often for complex string syntax.
-    // https://github.com/tree-sitter/tree-sitter/issues/1156
+
+    /// Tree-sitter nodes that we treat as indivisible atoms.
+    ///
+    /// This is particularly useful for strings, as some grammars use
+    /// several nodes for a single string literal. We don't want to
+    /// say e.g. the closing string delimiter moved, as it's confusing
+    /// and not well-balanced syntax.
+    ///
+    /// This is also useful for when tree-sitter nodes don't include
+    /// all the children in the source. This is known limitation of
+    /// tree-sitter, and occurs more often for complex string syntax.
+    /// <https://github.com/tree-sitter/tree-sitter/issues/1156>
     atom_nodes: HashSet<&'static str>,
+
+    /// We want to consider delimiter tokens as part of lists, not
+    /// standalone atoms. Tree-sitter includes delimiter tokens, so
+    /// mark which token pairs we consider to be delimiters.
     delimiter_tokens: Vec<(&'static str, &'static str)>,
+
+    /// Tree-sitter queries used for syntax highlighting this
+    /// language.
     highlight_queries: &'static str,
 }