Merge pull request #513 from Automattic/rust-doc-updates

`harper-core` Documentation Updates

Author: elijah-potter

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 underlying 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

@@ -1,3 +1,7 @@
+//! Frameworks and rules that locate errors in text.
+//!
+//! See the [`Linter`] trait and the [documentation for authoring a rule](https://writewithharper.com/docs/contributors/author-a-rule) for more information.
+
 mod an_a;
 mod avoid_curses;
 mod boring_words;
@@ -73,15 +77,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/patterns/is_not_title_case.rs

@@ -2,8 +2,8 @@ use crate::{make_title_case, Dictionary, Token, TokenStringExt};
 
 use super::Pattern;
 
-/// Will match full length of wrapped pattern __only if the matched
-/// text is not already title case__.
+/// Will match full length of wrapped pattern only if the matched
+/// text is not already title case.
 pub struct IsNotTitleCase<D: Dictionary> {
     inner: Box<dyn Pattern>,
     dict: D,

harper-core/src/patterns/mod.rs

@@ -1,3 +1,10 @@
+//! [`Pattern`]s are one of the more powerful ways to query text inside Harper, especially for beginners.
+//!
+//! Through the [`PatternLinter`](crate::linting::PatternLinter) trait, they make it much easier to
+//! build Harper [rules](crate::linting::Linter).
+//!
+//! See the page about [`SequencePattern`] for a concrete example of their use.
+
 use std::collections::VecDeque;
 
 use crate::{Document, Span, Token, VecExt};
@@ -127,7 +134,7 @@ where
     }
 }
 
-trait DocPattern {
+pub trait DocPattern {
     fn find_all_matches_in_doc(&self, document: &Document) -> Vec<Span>;
 }
 

harper-core/src/patterns/sequence_pattern.rs

@@ -6,6 +6,26 @@ use super::{NounPhrase, Pattern, RepeatingPattern, WordSet};
 use crate::{CharStringExt, Lrc, Token, TokenKind};
 
 /// A pattern that checks that a sequence of other patterns match.
+/// There are specific extension methods available, but you can also use [`Self::then`] to add
+/// arbitrary patterns.
+///
+/// ## Example
+///
+/// Let's say we wanted to locate places in a [`Document`] where an article is followed by a noun.
+/// We can do that with a `SequencePattern`.
+///
+/// ```rust
+/// use harper_core::patterns::{SequencePattern, DocPattern};
+/// use harper_core::{Document, Span};
+///
+/// let document = Document::new_markdown_default_curated("This is a test.");
+///
+/// let pattern = SequencePattern::default().then_article().then_whitespace().then_noun();
+/// let matches = pattern.find_all_matches_in_doc(&document);
+///
+/// // The pattern found that the tokens at indexes 4, 5, and 6 fit the criteria.
+/// assert_eq!(matches, vec![Span::new(4, 7)]);
+/// ```
 #[derive(Default)]
 pub struct SequencePattern {
     token_patterns: Vec<Box<dyn Pattern>>,
@@ -60,6 +80,7 @@ impl SequencePattern {
     gen_then_from_is!(adjective);
     gen_then_from_is!(apostrophe);
     gen_then_from_is!(hyphen);
+    gen_then_from_is!(article);
 
     pub fn then_word_set(self, set: WordSet) -> Self {
         self.then(Box::new(set))

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>;

packages/web/src/routes/docs/contributors/author-a-rule/+page.md

@@ -150,18 +150,18 @@ If you need any help writing or debugging rules, don't be afraid to contact the
 ### Using Visual Studio Code
 
 First make sure you have [the extension installed from the marketplace](https://marketplace.visualstudio.com/items?itemName=elijah-potter.harper).
-Then, can configure the path of the `harper-ls` binary the Visual Studio Code extension uses in settings.
+Then, configure the path of the `harper-ls` binary the Visual Studio Code extension uses in the settings page.
 Set it to `<harper repo>/target/release/harper-ls`.
 
 ![How to change the `harper-ls` path](/images/vscode_harper_path.webp)
 
-Now every time you want to test a change, you'll have to recompile `harper-ls` and reload Visual Studio Code using `Developer: Reload Window`.
+Every time you want to test a change, you'll have to recompile `harper-ls` and reload Visual Studio Code with the `Developer: Reload Window` command in the command palette.
 
 ```bash
 cargo build --release # Run in the monorepo to compile `harper-ls`.
 ```
 
 ## Elevate Your Pull Request
 
-Once you're satisfied with your rule, you can go ahead and elevate your pull requests to mark it as "ready for review."
+Once you're satisfied with your rule, you can go ahead and elevate your pull request to mark it as "ready for review."
 At that point, a maintainer on the Harper team take a look at it and (hopefully) merge it.