Refactor code-style

*   Add support for `null` as input in API types
*   Add more docs to JSDoc

Author: wooorm

lib/index.js

@@ -1,37 +1,52 @@
 /**
- * @typedef Options
- * @property {Test} [ignore]
- *
  * @typedef {import('hast').Text} Text
- * @typedef {import('hast').Parent} Parent
  * @typedef {import('hast').Root} Root
  * @typedef {import('hast').Element} Element
  * @typedef {import('hast').Content} Content
- * @typedef {Root|Content} Node
- *
  * @typedef {import('hast-util-is-element').Test} Test
  * @typedef {import('unist-util-visit-parents').VisitorResult} VisitorResult
+ */
+
+/**
+ * @typedef {Root | Content} Node
  *
  * @typedef RegExpMatchObject
+ *   Info on the match.
  * @property {number} index
+ *   The index of the search at which the result was found.
  * @property {string} input
+ *   A copy of the search string in the text node.
  * @property {[Root, ...Array<Element>, Text]} stack
+ *   All ancestors of the text node, where the last node is the text itself.
  *
- * @typedef {string|RegExp} Find
- * @typedef {string|ReplaceFunction} Replace
+ * @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 last parameter is a `RegExpMatchObject`.
+ * @returns {Array<Content> | Content | string | false | undefined | null}
+ *   Resulting nodes (where `string` is turned into a `Text` node).
  *
+ *   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.
+ *
+ * @typedef {string | RegExp} Find
+ * @typedef {string | ReplaceFunction} Replace
  * @typedef {[Find, Replace]} FindAndReplaceTuple
  * @typedef {Record<string, Replace>} FindAndReplaceSchema
  * @typedef {Array<FindAndReplaceTuple>} FindAndReplaceList
- *
  * @typedef {[RegExp, ReplaceFunction]} Pair
  * @typedef {Array<Pair>} Pairs
- */
-
-/**
- * @callback ReplaceFunction
- * @param {...any} parameters
- * @returns {Array<Content>|Content|string|false|undefined|null}
+ *
+ * @typedef Options
+ *   Configuration.
+ * @property {Test | null | undefined} [ignore]
+ *   Test for which elements to ignore.
  */
 
 import {visitParents} from 'unist-util-visit-parents'
@@ -43,15 +58,25 @@ const own = {}.hasOwnProperty
 export const defaultIgnore = ['title', 'script', 'style', 'svg', 'math']
 
 /**
+ * Find patterns in a tree and replace them.
+ *
+ * The algorithm searches the tree in *preorder* for complete values in `Text`
+ * nodes.
+ * Partial matches are not supported.
+ *
  * @param {Node} tree
- * @param {Find|FindAndReplaceSchema|FindAndReplaceList} find
- * @param {Replace|Options} [replace]
- * @param {Options} [options]
+ *   Tree to change.
+ * @param {Find | FindAndReplaceSchema | FindAndReplaceList} find
+ *   Patterns to find.
+ * @param {Replace | Options | null | undefined} [replace]
+ *   `Replace` (when `find` is `Find`) or configuration.
+ * @param {Options | null | undefined} [options]
+ *   Configuration (when `find` is not `Find`).
  */
 export function findAndReplace(tree, find, replace, options) {
-  /** @type {Options|undefined} */
+  /** @type {Options | null | undefined} */
   let settings
-  /** @type {FindAndReplaceSchema|FindAndReplaceList} */
+  /** @type {FindAndReplaceSchema | FindAndReplaceList} */
   let schema
 
   if (typeof find === 'string' || find instanceof RegExp) {
@@ -81,7 +106,7 @@ export function findAndReplace(tree, find, replace, options) {
   /** @type {import('unist-util-visit-parents/complex-types.js').BuildVisitor<Node, 'text'>} */
   function visitor(node, parents) {
     let index = -1
-    /** @type {Root|Element|undefined} */
+    /** @type {Root | Element | undefined} */
     let grandparent
 
     while (++index < parents.length) {
@@ -107,9 +132,14 @@ export function findAndReplace(tree, find, replace, options) {
   }
 
   /**
+   * Handle a text node which is not in an ignored parent.
+   *
    * @param {Text} node
-   * @param {Array<Root|Element>} parents
+   *   Text node.
+   * @param {Array<Root | Element>} parents
+   *   Parents.
    * @returns {VisitorResult}
+   *   Result.
    */
   function handler(node, parents) {
     const parent = parents[parents.length - 1]
@@ -120,15 +150,13 @@ export function findAndReplace(tree, find, replace, options) {
     let change = false
     /** @type {Array<Content>} */
     let nodes = []
-    /** @type {number|undefined} */
-    let position
 
     find.lastIndex = 0
 
     let match = find.exec(node.value)
 
     while (match) {
-      position = match.index
+      const position = match.index
       /** @type {RegExpMatchObject} */
       const matchObject = {
         index: match.index,
@@ -180,8 +208,12 @@ export function findAndReplace(tree, find, replace, options) {
 }
 
 /**
- * @param {FindAndReplaceSchema|FindAndReplaceList} schema
+ * Turn a schema into pairs.
+ *
+ * @param {FindAndReplaceSchema | FindAndReplaceList} schema
+ *   Schema.
  * @returns {Pairs}
+ *   Clean pairs.
  */
 function toPairs(schema) {
   /** @type {Pairs} */
@@ -215,16 +247,24 @@ function toPairs(schema) {
 }
 
 /**
+ * Turn a find into an expression.
+ *
  * @param {Find} find
+ *   Find.
  * @returns {RegExp}
+ *   Expression.
  */
 function toExpression(find) {
   return typeof find === 'string' ? new RegExp(escape(find), 'g') : find
 }
 
 /**
+ * Turn a replace into a function.
+ *
  * @param {Replace} replace
+ *   Replace.
  * @returns {ReplaceFunction}
+ *   Function.
  */
 function toFunction(replace) {
   return typeof replace === 'function' ? replace : () => replace