Merge pull request #979 from Automattic/doc-coverage

Improve doc coverage

Author: elijah-potter

harper-core/src/span.rs

@@ -5,6 +5,8 @@ use serde::{Deserialize, Serialize};
 use crate::CharStringExt;
 
 /// A window in a [`char`] sequence.
+///
+/// Although specific to `harper.js`, [this page may clear up any questions you have](https://writewithharper.com/docs/harperjs/spans).
 #[derive(Debug, Clone, Copy, Serialize, Deserialize, Default, PartialEq, Eq)]
 pub struct Span {
     pub start: usize,

packages/web/src/routes/docs/harperjs/configurerules/+page.md

@@ -0,0 +1,21 @@
+---
+title: Configure Rules
+---
+
+We add new [rules](/docs/rules) to Harper on a daily basis.
+As such, it is not recommended for consumers of `harper.js` to rely on any rule to exist.
+Further, consumers should allow space (in their UI, database, etc.) for additional rules to be added whenever a new version of `harper.js` is published.
+
+To make this easier, `harper.js` exposes a [`LintConfig`](/docs/harperjs/ref/harper.js.lintconfig.html) type, which can be obtained via `Linter.getLintConfig` and written using `Linter.setLintConfig`.
+
+Each key refers to a specific rule. Each rule can be disabled (set the value to `false`), enabled (set the value to `true`), or to the default (set the value to `undefined`).
+For example, the following code disables `SpellCheck`, enables `ExplanationMarks`, and sets `SameAs` to assume the default value.
+
+```javascript
+let linter = new WorkerLinter();
+
+await linter.setLintConfig({
+    SpellCheck: false,
+    ExplanationMarks: true,
+});
+```

packages/web/src/routes/docs/harperjs/spans/+page.md

@@ -0,0 +1,38 @@
+---
+title: Spans
+---
+
+When you lint a document using `harper.js`, you'll get back a series of `Lint` objects, each with a `span` method available.
+There are a number of questions that come up about this method.
+
+## What is a span?
+
+A span is a struct that contains a start index and an end index.
+The Rust code looks something like this:
+
+```rust
+struct Span {
+    start: usize,
+    end: usize
+}
+```
+
+For the uninitiated, a `usize` is an unsigned integer.
+Most commonly (and always in the context of a `Lint`), spans are referring to character windows.
+More precisely, spans are windows or slices into an array of [unicode scalar values](https://www.unicode.org/glossary/#unicode_scalar_value).
+This is less relevant to JavaScript consumers.
+Some get confused and believe these are indices into byte arrays (C-style strings).
+
+##  Why do I need to obtain the span through a method call?
+
+The actual span for a `Lint` is stored inside WebAssembly memory.
+In order to access that data from JavaScript, a tiny bit of WebAssembly code must be run to serialize it and convert its indices to JavaScript [number types](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number).
+
+## What can I use it for?
+
+In a `Lint`, the span represents two things:
+
+1. The location of the problematic text.
+1. The text that would be edited by the relevant suggestions.
+
+In other words, you use the span to underline the problem, then again to solve it.

packages/web/src/routes/docs/integrations/obsidian/+page.md

@@ -6,6 +6,8 @@ The Harper plugin is a powerful, privacy-first grammar and spell-checking tool d
 
 ![A screenshot of Obsidian with Harper installed](/images/obsidian_screenshot.webp)
 
+Unlike other offerings (like Grammarly) Harper explicitly ignores the contents of code fences and inline code blocks.
+
 ## Key Features
 
 ### Privacy-Focused

packages/web/vite.config.ts

@@ -90,6 +90,14 @@ export default defineConfig({
 									title: 'Linting',
 									to: '/docs/harperjs/linting',
 								},
+								{
+									title: 'Spans',
+									to: '/docs/harperjs/spans',
+								},
+								{
+									title: 'Configure Rules',
+									to: '/docs/harperjs/configurerules',
+								},
 								{
 									title: 'Node.js',
 									to: '/docs/harperjs/node',