Add improved docs

Author: wooorm

index.js

@@ -7,5 +7,6 @@
  * @typedef {import('./lib/index.js').Options} SearchOptions
  *   Deprecated form of `Options`.
  */
+// To do: next major: remove `SearchOptions`.
 
 export {search} from './lib/index.js'

lib/index.js

@@ -14,19 +14,27 @@
  *
  * @typedef {Array<string>} PhrasesList
  *   List of phrases.
+ *
+ *   Each phrase is a space-separated list of words, where each word will be
+ *   normalized to remove casing, apostrophes, and dashes.
+ *   Spaces in a pattern mean one or more whitespace nodes in the tree.
+ *   Instead of a word with letters, it’s also possible to use a wildcard
+ *   symbol (`*`, an asterisk) which will match any word in a pattern
+ *   (`alpha * charlie`).
+ *
  * @typedef {Record<string, unknown>} PhrasesMap
  *   Map where the keys are phrases.
  *
  * @callback Handler
- *   Function called when a pattern matches.
+ *   Handle a match.
  * @param {Array<Content>} nodes
  *   Match.
  * @param {number} index
- *   Index of first node of `nodes` in `parent.
+ *   Index of first node of `nodes` in `parent`.
  * @param {Parent} parent
  *   Parent of `nodes`.
- * @param {string} pattern
- *   The pattern that matched.
+ * @param {string} phrase
+ *   The phrase that matched.
  * @returns {void}
  *   Nothing.
  */
@@ -38,28 +46,24 @@ import {isLiteral} from 'nlcst-is-literal'
 const own = {}.hasOwnProperty
 
 /**
- * Search for patterns a tree.
+ * Search for phrases in a tree.
  *
  * @param {Node} tree
  *   Tree to search.
  * @param {PhrasesList | PhrasesMap} phrases
- *   Patterns.
+ *   Phrases to search for.
  * @param {Handler} handler
- *  Handler.
+ *   Handle a match
  * @param {boolean | Options} [options=false]
- *   Configuration.
+ *   Configuration (or `allowApostrophes`).
  * @returns {void}
  *   Nothing.
  */
 // To do: next major: remove boolean overload.
 // To do: next major: remove `PhrasesMap` support.
 export function search(tree, phrases, handler, options) {
   const config =
-    typeof options === 'boolean'
-      ? options
-        ? {allowApostrophes: true}
-        : {}
-      : options || {}
+    typeof options === 'boolean' ? {allowApostrophes: options} : options || {}
 
   if (!tree || !tree.type) {
     throw new Error('Expected node')

readme.md

@@ -8,7 +8,7 @@
 [![Backers][backers-badge]][collective]
 [![Chat][chat-badge]][chat]
 
-[nlcst][] utility to search for patterns in a tree.
+[nlcst][] utility to search for phrases in a tree.
 
 ## Contents
 
@@ -17,8 +17,11 @@
 *   [Install](#install)
 *   [Use](#use)
 *   [API](#api)
-    *   [`search(tree, patterns, handler[, allowApostrophes|options])`](#searchtree-patterns-handler-allowapostrophesoptions)
-    *   [`function handler(nodes, index, parent, pattern)`](#function-handlernodes-index-parent-pattern)
+    *   [`search(tree, phrases, handler[, allowApostrophes|options])`](#searchtree-phrases-handler-allowapostrophesoptions)
+    *   [`Handler`](#handler)
+    *   [`Options`](#options)
+    *   [`PhrasesList`](#phraseslist)
+    *   [`PhrasesMap`](#phrasesmap)
 *   [Types](#types)
 *   [Compatibility](#compatibility)
 *   [Related](#related)
@@ -27,7 +30,7 @@
 
 ## What is this?
 
-This utility can search for patterns (words and phrases) in trees.
+This utility can search for phrases (words and phrases) in trees.
 
 ## When should I use this?
 
@@ -37,7 +40,7 @@ and phrases.
 ## Install
 
 This package is [ESM only][esm].
-In Node.js (version 12.20+, 14.14+, 16.0+, 18.0+), install with [npm][]:
+In Node.js (version 14.14+ and 16.0+), install with [npm][]:
 
 ```sh
 npm install nlcst-search
@@ -46,14 +49,14 @@ npm install nlcst-search
 In Deno with [`esm.sh`][esmsh]:
 
 ```js
-import {search} from "https://esm.sh/nlcst-search@3"
+import {search} from 'https://esm.sh/nlcst-search@3'
 ```
 
 In browsers with [`esm.sh`][esmsh]:
 
 ```html
 <script type="module">
-  import {search} from "https://esm.sh/nlcst-search@3?bundle"
+  import {search} from 'https://esm.sh/nlcst-search@3?bundle'
 </script>
 ```
 
@@ -104,82 +107,104 @@ search(tree, ['do blocklevel'], function(nodes) {
 
 ## API
 
-This package exports the identifier `search`.
+This package exports the identifier [`search`][search].
 There is no default export.
 
-### `search(tree, patterns, handler[, allowApostrophes|options])`
+### `search(tree, phrases, handler[, allowApostrophes|options])`
 
-Search for patterns a [tree][].
+Search for phrases in a tree.
 
 ##### Parameters
 
-###### `node`
+*   `tree` ([`Node`][node])
+    — tree to search
+*   `phrases` ([`PhrasesList`][phraseslist] or [`PhrasesMap`][phrasesmap])
+    — phrases to search for
+*   `handler` ([`Handler`][handler])
+    — handle a match
+*   `allowApostrophes` (`boolean`)
+    — shortcut for `options` of `{allowApostrophes: boolean}`
+*   `options` ([`Options`][options])
+    — configuration
 
-[Tree][] to search in ([`Node`][node]).
+###### Returns
 
-###### `patterns`
+Nothing (`void`).
 
-Patterns to search for (`Array<string>` or `Record<string, unknown>`).
-If an `Object`, uses its keys as patterns.
-Each pattern is a space-separated list of words, where each word is
-[normalized][nlcst-normalize] to remove casing, apostrophes, and dashes.
-Spaces in a pattern mean zero or more white space nodes in the tree.
-Instead of a word, it’s also possible to use a wildcard symbol (`*`, an
-asterisk), that matches any word in a pattern (`alpha * charlie`).
+### `Handler`
 
-###### `handler`
+Handle a match (TypeScript type).
 
-Handler called when a match is found ([`Handler`][fn-handler]).
+###### Parameters
 
-###### `allowApostrophes`
+*   `nodes` ([`Array<Node>`][node])
+    — match
+*   `index` (`number`)
+    — index of first node of `nodes` in `parent`
+*   `parent` ([`Node`][node])
+    — parent of `nodes`
+*   `phrase` (`string`)
+    — the phrase that matched
 
-Treated as `options.allowApostrophes`.
+###### Returns
 
-###### `options.allowApostrophes`
+Nothing (`void`).
 
-Passed to [`nlcst-normalize`][nlcst-normalize] (`boolean`, default: `false`).
+### `Options`
+
+Configuration (TypeScript type).
 
-###### `options.allowDashes`
+##### Fields
+
+###### `allowApostrophes`
 
 Passed to [`nlcst-normalize`][nlcst-normalize] (`boolean`, default: `false`).
 
-###### `options.allowLiterals`
+###### `allowDashes`
 
-Include [literal][] phrases (`boolean`, default: `false`).
+Passed to [`nlcst-normalize`][nlcst-normalize] (`boolean`, default: `false`).
 
-### `function handler(nodes, index, parent, pattern)`
+###### `allowLiterals`
 
-Handler called when a match is found.
+Include [literal][] phrases (`boolean`, default: `false`).
 
-##### Parameters
+### `PhrasesList`
 
-###### `nodes`
+List of phrases (TypeScript type).
 
-List of [sibling][]s that match `pattern` ([`Array<Node>`][node]).
+Each phrase is a space-separated list of words, where each word will be
+[normalized][nlcst-normalize] to remove casing, apostrophes, and dashes.
+Spaces in a pattern mean one or more whitespace nodes in the tree.
+Instead of a word with letters, it’s also possible to use a wildcard symbol
+(`*`, an asterisk) which will match any word in a pattern (`alpha * charlie`).
 
-###### `index`
+###### Type
 
-[Index][] where the match starts in `parent` (`number`).
+```ts
+type PhrasesList = Array<string>
+```
 
-###### `parent`
+### `PhrasesMap`
 
-[Parent][] node of `nodes` ([`Node`][node]).
+Map of phrases (TypeScript type).
 
-###### `pattern`
+###### Type
 
-The matched pattern (`string`).
+```ts
+type PhrasesMap = Record<string, unknown>
+```
 
 ## Types
 
 This package is fully typed with [TypeScript][].
-It exports the additional types `Options`, `PhrasesList`, `PhrasesMap`, and
-`Handler`.
+It exports the additional types [`Handler`][handler], [`Options`][options],
+[`PhrasesList`][phraseslist], and [`PhrasesMap`][phrasesmap].
 
 ## Compatibility
 
 Projects maintained by the unified collective are compatible with all maintained
 versions of Node.js.
-As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+.
+As of now, that is Node.js 14.14+ and 16.0+.
 Our projects sometimes work with older versions, but this is not guaranteed.
 
 ## Related
@@ -259,12 +284,12 @@ abide by its terms.
 
 [nlcst-normalize]: https://github.com/syntax-tree/nlcst-normalize
 
-[fn-handler]: #function-handlernodes-index-parent-pattern
+[search]: #searchtree-phrases-handler-allowapostrophesoptions
 
-[tree]: https://github.com/syntax-tree/unist#tree
+[handler]: #handler
 
-[sibling]: https://github.com/syntax-tree/unist#sibling
+[options]: #options
 
-[index]: https://github.com/syntax-tree/unist#index
+[phraseslist]: #phraseslist
 
-[parent]: https://github.com/syntax-tree/unist#parent-1
+[phrasesmap]: #phrasesmap