From 754d03816abe2ed0b4ab46ab5f19d208b3079654 Mon Sep 17 00:00:00 2001
From: Titus Wormer <tituswormer@gmail.com>
Date: Tue, 24 Jan 2023 15:17:56 +0100
Subject: [PATCH] Refactor code-style

*   Add more docs to JSDoc
*   Add support for `null` in input of API types
---
 index.d.ts   |  3 +--
 index.js     |  3 +--
 lib/index.js | 34 ++++++++++++++++++++++++++--------
 3 files changed, 28 insertions(+), 12 deletions(-)

diff --git a/index.d.ts b/index.d.ts
index e2a025f..c6ebdb0 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -5,6 +5,5 @@ export type {
   Index,
   VisitorResult
 } from 'unist-util-visit-parents'
-export {CONTINUE, EXIT, SKIP} from 'unist-util-visit-parents'
 export type {Visitor, BuildVisitor} from './lib/index.js'
-export {visit} from './lib/index.js'
+export {CONTINUE, EXIT, SKIP, visit} from './lib/index.js'
diff --git a/index.js b/index.js
index 8eb53a3..4747999 100644
--- a/index.js
+++ b/index.js
@@ -1,3 +1,2 @@
 // Note: types exported from `index.d.ts`
-export {CONTINUE, EXIT, SKIP} from 'unist-util-visit-parents'
-export {visit} from './lib/index.js'
+export {CONTINUE, EXIT, SKIP, visit} from './lib/index.js'
diff --git a/lib/index.js b/lib/index.js
index 0602c81..180bd14 100644
--- a/lib/index.js
+++ b/lib/index.js
@@ -112,22 +112,39 @@
 import {visitParents} from 'unist-util-visit-parents'
 
 /**
- * Visit children of tree which pass test.
+ * Visit nodes.
+ *
+ * This algorithm performs *depth-first* *tree traversal* in *preorder*
+ * (**NLR**) or if `reverse` is given, in *reverse preorder* (**NRL**).
+ *
+ * You can choose for which nodes `visitor` is called by passing a `test`.
+ * For complex tests, you should test yourself in `visitor`, as it will be
+ * faster and will have improved type information.
+ *
+ * Walking the tree is an intensive task.
+ * Make use of the return values of the visitor when possible.
+ * Instead of walking a tree multiple times, walk it once, use `unist-util-is`
+ * to check if a node matches, and then perform different operations.
+ *
+ * You can change the tree.
+ * See `Visitor` for more info.
  *
  * @param tree
- *   Tree to walk
- * @param [test]
+ *   Tree to traverse.
+ * @param test
  *   `unist-util-is`-compatible test
  * @param visitor
- *   Function called for nodes that pass `test`.
+ *   Handle each node.
  * @param reverse
- *   Traverse in reverse preorder (NRL) instead of preorder (NLR) (default).
+ *   Traverse in reverse preorder (NRL) instead of the default preorder (NLR).
+ * @returns
+ *   Nothing.
  */
 export const visit =
   /**
    * @type {(
-   *   (<Tree extends Node, Check extends Test>(tree: Tree, test: Check, visitor: BuildVisitor<Tree, Check>, reverse?: boolean) => void) &
-   *   (<Tree extends Node>(tree: Tree, visitor: BuildVisitor<Tree>, reverse?: boolean) => void)
+   *   (<Tree extends Node, Check extends Test>(tree: Tree, test: Check, visitor: BuildVisitor<Tree, Check>, reverse?: boolean | null | undefined) => void) &
+   *   (<Tree extends Node>(tree: Tree, visitor: BuildVisitor<Tree>, reverse?: boolean | null | undefined) => void)
    * )}
    */
   (
@@ -135,7 +152,8 @@ export const visit =
      * @param {Node} tree
      * @param {Test} test
      * @param {Visitor} visitor
-     * @param {boolean} [reverse]
+     * @param {boolean | null | undefined} [reverse]
+     * @returns {void}
      */
     function (tree, test, visitor, reverse) {
       if (typeof test === 'function' && typeof visitor !== 'function') {