From e0fa69ca6db5b2dcae1501f129926a0eb09c1748 Mon Sep 17 00:00:00 2001 From: Wilfred Hughes Date: Sun, 21 Nov 2021 23:22:08 -0800 Subject: [PATCH] Expand and improve docstrings --- src/context.rs | 13 +++++++++++++ src/hunks.rs | 14 ++++++++++++-- src/lines.rs | 2 ++ src/style.rs | 7 ++++++- src/tree_sitter_parser.rs | 35 ++++++++++++++++++++++++----------- 5 files changed, 57 insertions(+), 14 deletions(-) diff --git a/src/context.rs b/src/context.rs index e66da5466e..15c897ac1f 100644 --- a/src/context.rs +++ b/src/context.rs @@ -1,3 +1,5 @@ +//! Calculate which nearby lines should also be displayed. + use std::collections::{HashMap, HashSet}; use crate::{ @@ -5,6 +7,11 @@ use crate::{ 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> { @@ -43,14 +50,20 @@ pub fn opposite_positions(mps: &[MatchedPos]) -> HashMap>, diff --git a/src/hunks.rs b/src/hunks.rs index b88b2269a5..2bd1659a40 100644 --- a/src/hunks.rs +++ b/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, Option)>, @@ -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, Option)], ) -> Vec<(Option, Option)> { diff --git a/src/lines.rs b/src/lines.rs index 1649f1fe3c..a199f10795 100644 --- a/src/lines.rs +++ b/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); diff --git a/src/style.rs b/src/style.rs index b47e716aef..d6e216827f 100644 --- a/src/style.rs +++ b/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 { let mut res = vec![]; let mut s = s; diff --git a/src/tree_sitter_parser.rs b/src/tree_sitter_parser.rs index 117c700aa3..4449fa21f1 100644 --- a/src/tree_sitter_parser.rs +++ b/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. + /// 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, }