docs(core): add doc-comments to important structs

harper-core/src/char_string.rs

@@ -4,6 +4,7 @@ use smallvec::SmallVec;
 /// Most English words are fewer than 12 characters.
 pub type CharString = SmallVec<[char; 12]>;
 
+/// Extensions to character sequences that make them easier to wrangle.
 pub trait CharStringExt {
     fn to_lower(&self) -> CharString;
     fn to_string(&self) -> String;

harper-core/src/linting/lint.rs

@@ -5,11 +5,21 @@ use serde::{Deserialize, Serialize};
 
 use crate::Span;
 
+/// An error found in text.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Lint {
+    /// The location in the source text the error lies.
+    /// Important for automatic lint resolution through [`Self::suggestions`].
     pub span: Span,
+    /// The general category the lint belongs to.
+    /// Mostly used for UI elements in integrations.
     pub lint_kind: LintKind,
+    /// A list of zero or more suggested edits that would resolve the underling problem.
+    /// See [`Suggestion`].
     pub suggestions: Vec<Suggestion>,
+    /// A message to be displayed to the user describing the specific error found.
+    ///
+    /// You may use the [`format`] macro to generate more complex messages.
     pub message: String,
     /// A numerical value for the importance of a lint.
     /// Lower = more important.
@@ -28,6 +38,9 @@ impl Default for Lint {
     }
 }
 
+/// The general category a [`Lint`] falls into.
+/// There's no reason not to add a new item here if you are adding a new rule that doesn't fit
+/// the existing categories.
 #[derive(Debug, Clone, Copy, Serialize, Deserialize, Is, Default)]
 pub enum LintKind {
     Spelling,
@@ -60,11 +73,14 @@ impl Display for LintKind {
     }
 }
 
+/// A suggested edit that could resolve a [`Lint`].
 #[derive(Debug, Clone, Serialize, Deserialize, Is, PartialEq, Eq)]
 pub enum Suggestion {
+    /// Replace the offending text with a specific character sequence.
     ReplaceWith(Vec<char>),
     /// Insert the provided characters _after_ the offending text.
     InsertAfter(Vec<char>),
+    /// Remove the offending text.
     Remove,
 }
 

harper-core/src/linting/lint_group.rs

@@ -56,6 +56,7 @@ macro_rules! create_lint_group_config {
                 }
             }
 
+            /// A collection of all officially supported
             #[derive(Debug, Clone, Copy, Serialize, Deserialize, Default)]
             pub struct LintGroupConfig {
                 $(

harper-core/src/linting/mod.rs

@@ -73,15 +73,33 @@ pub use wrong_quotes::WrongQuotes;
 
 use crate::Document;
 
+/// A __stateless__ rule that searches documents for grammatical errors.
+///
+/// Commonly implemented via [`PatternLinter`].
+///
+/// See also: [`LintGroup`].
 #[cfg(not(feature = "concurrent"))]
 pub trait Linter {
+    /// Analyzes a document and produces zero or more [`Lint`]s.
+    /// We pass `self` mutably for caching purposes.
     fn lint(&mut self, document: &Document) -> Vec<Lint>;
+    /// A user-facing description of what kinds of grammatical errors this rule looks for.
+    /// It is usually shown in settings menus.
     fn description(&self) -> &str;
 }
 
+/// A __stateless__ rule that searches documents for grammatical errors.
+///
+/// Commonly implemented via [`PatternLinter`].
+///
+/// See also: [`LintGroup`].
 #[cfg(feature = "concurrent")]
 pub trait Linter: Send + Sync {
+    /// Analyzes a document and produces zero or more [`Lint`]s.
+    /// We pass `self` mutably for caching purposes.
     fn lint(&mut self, document: &Document) -> Vec<Lint>;
+    /// A user-facing description of what kinds of grammatical errors this rule looks for.
+    /// It is usually shown in settings menus.
     fn description(&self) -> &str;
 }
 

harper-core/src/linting/pattern_linter.rs

@@ -2,19 +2,35 @@ use super::{Lint, Linter};
 use crate::patterns::Pattern;
 use crate::{Token, TokenStringExt};
 
+/// A trait that searches for [`Pattern`]s in [`Document`](crate::Document)s.
+///
+/// Makes use of [`TokenStringExt::iter_chunks`] to avoid matching across sentence or clause
+/// boundaries.
 #[cfg(not(feature = "concurrent"))]
 pub trait PatternLinter {
     /// A simple getter for the pattern to be searched for.
     fn pattern(&self) -> &dyn Pattern;
+    /// If any portions of a [`Document`](crate::Document) match [`Self::pattern`], they are passed through [`PatternLinter::match_to_lint`] to be
+    /// transformed into a [`Lint`] for editor consumption.
     fn match_to_lint(&self, matched_tokens: &[Token], source: &[char]) -> Lint;
-    fn description<'a>(&'a self) -> &'a str;
+    /// A user-facing description of what kinds of grammatical errors this rule looks for.
+    /// It is usually shown in settings menus.
+    fn description(&self) -> &str;
 }
 
+/// A trait that searches for [`Pattern`]s in [`Document`](crate::Document)s.
+///
+/// Makes use of [`TokenStringExt::iter_chunks`] to avoid matching across sentence or clause
+/// boundaries.
 #[cfg(feature = "concurrent")]
 pub trait PatternLinter: Send + Sync {
     /// A simple getter for the pattern to be searched for.
     fn pattern(&self) -> &dyn Pattern;
+    /// If any portions of a [`Document`](crate::Document) match [`Self::pattern`], they are passed through [`PatternLinter::match_to_lint`] to be
+    /// transformed into a [`Lint`] for editor consumption.
     fn match_to_lint(&self, matched_tokens: &[Token], source: &[char]) -> Lint;
+    /// A user-facing description of what kinds of grammatical errors this rule looks for.
+    /// It is usually shown in settings menus.
     fn description(&self) -> &str;
 }
 

harper-core/src/spell/dictionary.rs

@@ -3,6 +3,10 @@ use blanket::blanket;
 use super::FuzzyMatchResult;
 use crate::WordMetadata;
 
+/// An in-memory database that contains everything necessary to parse and analyze English text.
+///
+/// See also: [`FstDictionary`](super::FstDictionary) and
+/// [`FullDictionary`](super::FullDictionary).
 #[blanket(derive(Arc))]
 pub trait Dictionary: Send + Sync {
     /// Check if the dictionary contains a given word.

harper-core/src/token.rs

@@ -71,6 +71,7 @@ macro_rules! create_fns_for {
     };
 }
 
+/// Extension methods for [`Token`] sequences that make them easier to wrangle and query.
 pub trait TokenStringExt {
     fn first_sentence_word(&self) -> Option<Token>;
     fn first_non_whitespace(&self) -> Option<Token>;