Add improved docs

Author: wooorm

lib/index.js

@@ -22,26 +22,36 @@
  * @callback ReplaceFunction
  *   Callback called when a search matches.
  * @param {...any} parameters
- *   The parameters are the result of the search expressions, which can be
- *   several if a regex captures groups.
+ *   The parameters are the result of corresponding search expression:
  *
- *   The last parameter is a `RegExpMatchObject`.
+ *   * `value` (`string`) — whole match
+ *   * `...capture` (`Array<string>`) — matches from regex capture groups
+ *   * `match` (`RegExpMatchObject`) — info on the match
  * @returns {Array<Content> | Content | string | false | undefined | null}
- *   Resulting nodes (where `string` is turned into a `Text` node).
+ *   Thing to replace with.
  *
- *   The values `null` and `undefined` and an empty string mean the match is
- *   removed.
- *
- *   The value `false` means that this isn’t a match after all, and it is not
- *   replaced.
+ *   * when `null`, `undefined`, `''`, remove the match
+ *   * …or when `false`, do not replace at all
+ *   * …or when `string`, replace with a text node of that value
+ *   * …or when `Node` or `Array<Node>`, replace with those nodes
  *
  * @typedef {string | RegExp} Find
- * @typedef {string | ReplaceFunction} Replace
- * @typedef {[Find, Replace]} FindAndReplaceTuple
- * @typedef {Record<string, Replace>} FindAndReplaceSchema
+ *   Pattern to find.
+ *
+ *   Strings are escaped and then turned into global expressions.
+ *
  * @typedef {Array<FindAndReplaceTuple>} FindAndReplaceList
+ *   Several find and replaces, in array form.
+ * @typedef {Record<string, Replace>} FindAndReplaceSchema
+ *   Several find and replaces, in object form.
+ * @typedef {[Find, Replace]} FindAndReplaceTuple
+ *   Find and replace in tuple form.
+ * @typedef {string | ReplaceFunction} Replace
+ *   Thing to replace with.
  * @typedef {[RegExp, ReplaceFunction]} Pair
+ *   Normalized find and replace.
  * @typedef {Array<Pair>} Pairs
+ *   All find and replaced.
  *
  * @typedef Options
  *   Configuration.
@@ -55,7 +65,14 @@ import escape from 'escape-string-regexp'
 
 const own = {}.hasOwnProperty
 
-export const defaultIgnore = ['title', 'script', 'style', 'svg', 'math']
+/**
+ * Default tag names to ignore.
+ *
+ * The defaults are `math`, `script`, `style`, `svg`, and `title`.
+ *
+ * @type {Array<string>}
+ */
+export const defaultIgnore = ['math', 'script', 'style', 'svg', 'title']
 
 /**
  * Find patterns in a tree and replace them.
@@ -64,14 +81,18 @@ export const defaultIgnore = ['title', 'script', 'style', 'svg', 'math']
  * nodes.
  * Partial matches are not supported.
  *
- * @param {Node} tree
+ * @template {Node} Tree
+ *   Node type.
+ * @param {Tree} tree
  *   Tree to change.
  * @param {Find | FindAndReplaceSchema | FindAndReplaceList} find
  *   Patterns to find.
  * @param {Replace | Options | null | undefined} [replace]
- *   `Replace` (when `find` is `Find`) or configuration.
+ *   Things to replace with (when `find` is `Find`) or configuration.
  * @param {Options | null | undefined} [options]
  *   Configuration (when `find` is not `Find`).
+ * @returns {Tree}
+ *   Given, modified, tree.
  */
 export function findAndReplace(tree, find, replace, options) {
   /** @type {Options | null | undefined} */
@@ -101,6 +122,7 @@ export function findAndReplace(tree, find, replace, options) {
     visitParents(tree, 'text', visitor)
   }
 
+  // To do next major: don’t return the given tree.
   return tree
 
   /** @type {import('unist-util-visit-parents/complex-types.js').BuildVisitor<Node, 'text'>} */

readme.md

@@ -18,6 +18,15 @@
 *   [Use](#use)
 *   [API](#api)
     *   [`findAndReplace(tree, find, replace[, options])`](#findandreplacetree-find-replace-options)
+    *   [`defaultIgnore`](#defaultignore)
+    *   [`Find`](#find)
+    *   [`FindAndReplaceList`](#findandreplacelist)
+    *   [`FindAndReplaceSchema`](#findandreplaceschema)
+    *   [`FindAndReplaceTuple`](#findandreplacetuple)
+    *   [`Options`](#options)
+    *   [`RegExpMatchObject`](#regexpmatchobject)
+    *   [`Replace`](#replace)
+    *   [`ReplaceFunction`](#replacefunction)
 *   [Types](#types)
 *   [Compatibility](#compatibility)
 *   [Security](#security)
@@ -40,7 +49,7 @@ One example is when you have some form of “mentions” (such as
 ## Install
 
 This package is [ESM only][esm].
-In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
+In Node.js (version 14.14+ and or 16.0+), install with [npm][]:
 
 ```sh
 npm install hast-util-find-and-replace
@@ -118,12 +127,14 @@ element<p>[9]
 
 ## API
 
-This package exports the identifiers `findAndReplace` and `defaultIgnore`.
+This package exports the identifiers [`defaultIgnore`][defaultignore] and
+[`findAndReplace`][findandreplace].
 There is no default export.
 
 ### `findAndReplace(tree, find, replace[, options])`
 
 Find patterns in a tree and replace them.
+
 The algorithm searches the tree in *[preorder][]* for complete values in
 [`Text`][text] nodes.
 Partial matches are not supported.
@@ -136,41 +147,156 @@ Partial matches are not supported.
 ###### Parameters
 
 *   `tree` ([`Node`][node])
-*   `find` (`string` or `RegExp`)
-    — value to find and remove (`string`s are escaped and turned into a global
-    `RegExp`)
-*   `replace` (`string` or `Function`)
-    — value to insert.
-    `string`s are turned into a [`Text`][text] node,
-    `Function`s are called with the results of calling `RegExp.exec` as
-    arguments, and they can return a [`Node`][node], a `string` (which is
-    wrapped in a [`Text`][text] node), or `false` to not replace
-*   `search` (`Array` or `Object`)
-    — perform multiple find-and-replaces.
-    Either an `Array` of tuples (`Array`s) with `find` (at `0`) and `replace`
-    (at `1`), or an `Object` where each key is `find` and each value is
-    the corresponding `replace`
-*   `options.ignore` (`Test`, default: `['title', 'script', 'style', 'svg',
-    'math']`)
-    — any [`hast-util-is-element`][test] compatible test (the default list is
-    exported as `defaultIgnore`)
+    — tree to change
+*   `find` ([`Find`][find])
+    — value to find and remove
+*   `replace` ([`Replace`][replace])
+    — thing to replace with
+*   `search` ([`FindAndReplaceSchema`][findandreplaceschema] or
+    [`FindAndReplaceList`][findandreplacelist])
+    — several find and replaces
+*   `options` ([`Options`][options])
+    — configuration
 
 ###### Returns
 
-The given `tree` ([`Node`][node]).
+Given, modified, tree ([`Node`][node]).
+
+### `defaultIgnore`
+
+Default tag names to ignore.
+
+The defaults are `math`, `script`, `style`, `svg`, and `title`.
+
+###### Type
+
+```ts
+type defaultIgnore = Array<string>
+```
+
+### `Find`
+
+Pattern to find (TypeScript type).
+
+Strings are escaped and then turned into global expressions.
+
+###### Type
+
+```ts
+type Find = string | RegExp
+```
+
+### `FindAndReplaceList`
+
+Several find and replaces, in array form (TypeScript type).
+
+###### Type
+
+```ts
+type FindAndReplaceList = Array<FindAndReplaceTuple>
+```
+
+See [`FindAndReplaceTuple`][findandreplacetuple].
+
+### `FindAndReplaceSchema`
+
+Several find and replaces, in object form (TypeScript type).
+
+###### Type
+
+```ts
+type FindAndReplaceSchema = Record<string, Replace>
+```
+
+See [`Replace`][replace].
+
+### `FindAndReplaceTuple`
+
+Find and replace in tuple form (TypeScript type).
+
+###### Type
+
+```ts
+type FindAndReplaceTuple = [Find, Replace]
+```
+
+See [`Find`][find] and [`Replace`][replace].
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Fields
+
+*   `ignore` ([`Test`][test], optional)
+    — test for which elements to ignore
+
+### `RegExpMatchObject`
+
+Info on the match (TypeScript type).
+
+###### Fields
+
+*   `index` (`number`)
+    — the index of the search at which the result was found
+*   `input` (`string`)
+    — a copy of the search string in the text node
+*   `stack` ([`Array<Node>`][node])
+    — all ancestors of the text node, where the last node is the text itself
+
+### `Replace`
+
+Thing to replace with (TypeScript type).
+
+###### Type
+
+```ts
+type Replace = string | ReplaceFunction
+```
+
+See [`ReplaceFunction`][replacefunction].
+
+### `ReplaceFunction`
+
+Callback called when a search matches (TypeScript type).
+
+###### Parameters
+
+The parameters are the result of corresponding search expression:
+
+*   `value` (`string`)
+    — whole match
+*   `...capture` (`Array<string>`)
+    — matches from regex capture groups
+*   `match` ([`RegExpMatchObject`][regexpmatchobject])
+    — info on the match
+
+###### Returns
+
+Thing to replace with:
+
+*   when `null`, `undefined`, `''`, remove the match
+*   …or when `false`, do not replace at all
+*   …or when `string`, replace with a text node of that value
+*   …or when `Node` or `Array<Node>`, replace with those nodes
 
 ## Types
 
 This package is fully typed with [TypeScript][].
-It exports the additional types `Find`, `Replace`, `ReplaceFunction`,
-`FindAndReplaceTuple`, `FindAndReplaceSchema`, `FindAndReplaceList`,
-`RegExpMatchObject`, and `Options`.
+It exports the additional types [`Find`][find],
+[`FindAndReplaceList`][findandreplacelist],
+[`FindAndReplaceSchema`][findandreplaceschema],
+[`FindAndReplaceTuple`][findandreplacetuple],
+[`Options`][options],
+[`RegExpMatchObject`][regexpmatchobject],
+[`Replace`][replace], and
+[`ReplaceFunction`][replacefunction].
 
 ## 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+, and 16.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.
 
 ## Security
@@ -277,4 +403,24 @@ abide by its terms.
 
 [hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize
 
-[test]: https://github.com/syntax-tree/hast-util-is-element#api
+[test]: https://github.com/syntax-tree/hast-util-is-element#test
+
+[defaultignore]: #defaultignore
+
+[findandreplace]: #findandreplacetree-find-replace-options
+
+[options]: #options
+
+[find]: #find
+
+[replace]: #replace
+
+[replacefunction]: #replacefunction
+
+[findandreplacelist]: #findandreplacelist
+
+[findandreplaceschema]: #findandreplaceschema
+
+[findandreplacetuple]: #findandreplacetuple
+
+[regexpmatchobject]: #regexpmatchobject