Offline, privacy-first grammar checker. Fast, open-source, Rust-powered
docs(core): add doc-comments to important `struct`s
Elijah Potter6ebaa449838a
diff --git a/harper-core/src/char_string.rs b/harper-core/src/char_string.rsindex 899f5bff8..fa151adc0 100644--- a/harper-core/src/char_string.rs+++ b/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;diff --git a/harper-core/src/linting/lint.rs b/harper-core/src/linting/lint.rsindex 4759a625b..d490e9877 100644--- a/harper-core/src/linting/lint.rs+++ b/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,}diff --git a/harper-core/src/linting/lint_group.rs b/harper-core/src/linting/lint_group.rsindex f1e9174dd..2eb1a9095 100644--- a/harper-core/src/linting/lint_group.rs+++ b/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 {$(diff --git a/harper-core/src/linting/mod.rs b/harper-core/src/linting/mod.rsindex a68b2aca9..1f329af3b 100644--- a/harper-core/src/linting/mod.rs+++ b/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;}diff --git a/harper-core/src/linting/pattern_linter.rs b/harper-core/src/linting/pattern_linter.rsindex 4fed20727..f66a97fb7 100644--- a/harper-core/src/linting/pattern_linter.rs+++ b/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;}diff --git a/harper-core/src/spell/dictionary.rs b/harper-core/src/spell/dictionary.rsindex 7fb4e5c66..d7860dc89 100644--- a/harper-core/src/spell/dictionary.rs+++ b/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.diff --git a/harper-core/src/token.rs b/harper-core/src/token.rsindex f33c4a2b4..83eb246f1 100644--- a/harper-core/src/token.rs+++ b/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>;