Skip to content

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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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>;