|
112 | 112 | import {visitParents} from 'unist-util-visit-parents'
|
113 | 113 |
|
114 | 114 | /**
|
115 |
| - * Visit children of tree which pass test. |
| 115 | + * Visit nodes. |
| 116 | + * |
| 117 | + * This algorithm performs *depth-first* *tree traversal* in *preorder* |
| 118 | + * (**NLR**) or if `reverse` is given, in *reverse preorder* (**NRL**). |
| 119 | + * |
| 120 | + * You can choose for which nodes `visitor` is called by passing a `test`. |
| 121 | + * For complex tests, you should test yourself in `visitor`, as it will be |
| 122 | + * faster and will have improved type information. |
| 123 | + * |
| 124 | + * Walking the tree is an intensive task. |
| 125 | + * Make use of the return values of the visitor when possible. |
| 126 | + * Instead of walking a tree multiple times, walk it once, use `unist-util-is` |
| 127 | + * to check if a node matches, and then perform different operations. |
| 128 | + * |
| 129 | + * You can change the tree. |
| 130 | + * See `Visitor` for more info. |
116 | 131 | *
|
117 | 132 | * @param tree
|
118 |
| - * Tree to walk |
119 |
| - * @param [test] |
| 133 | + * Tree to traverse. |
| 134 | + * @param test |
120 | 135 | * `unist-util-is`-compatible test
|
121 | 136 | * @param visitor
|
122 |
| - * Function called for nodes that pass `test`. |
| 137 | + * Handle each node. |
123 | 138 | * @param reverse
|
124 |
| - * Traverse in reverse preorder (NRL) instead of preorder (NLR) (default). |
| 139 | + * Traverse in reverse preorder (NRL) instead of the default preorder (NLR). |
| 140 | + * @returns |
| 141 | + * Nothing. |
125 | 142 | */
|
126 | 143 | export const visit =
|
127 | 144 | /**
|
128 | 145 | * @type {(
|
129 |
| - * (<Tree extends Node, Check extends Test>(tree: Tree, test: Check, visitor: BuildVisitor<Tree, Check>, reverse?: boolean) => void) & |
130 |
| - * (<Tree extends Node>(tree: Tree, visitor: BuildVisitor<Tree>, reverse?: boolean) => void) |
| 146 | + * (<Tree extends Node, Check extends Test>(tree: Tree, test: Check, visitor: BuildVisitor<Tree, Check>, reverse?: boolean | null | undefined) => void) & |
| 147 | + * (<Tree extends Node>(tree: Tree, visitor: BuildVisitor<Tree>, reverse?: boolean | null | undefined) => void) |
131 | 148 | * )}
|
132 | 149 | */
|
133 | 150 | (
|
134 | 151 | /**
|
135 | 152 | * @param {Node} tree
|
136 | 153 | * @param {Test} test
|
137 | 154 | * @param {Visitor} visitor
|
138 |
| - * @param {boolean} [reverse] |
| 155 | + * @param {boolean | null | undefined} [reverse] |
| 156 | + * @returns {void} |
139 | 157 | */
|
140 | 158 | function (tree, test, visitor, reverse) {
|
141 | 159 | if (typeof test === 'function' && typeof visitor !== 'function') {
|
|
0 commit comments