Refactor code-style

*   Add more docs to JSDoc
*   Improve performance

Author: wooorm

lib/index.js

@@ -1,8 +1,13 @@
 /**
- * @typedef {import('mdast').Root|import('mdast').Content} Node
+ * @typedef {import('mdast').Root} Root
+ * @typedef {import('mdast').Content} Content
  * @typedef {import('mdast').Heading} Heading
  */
 
+/**
+ * @typedef {Content | Root} Node
+ */
+
 import {visit} from 'unist-util-visit'
 
 const max = 6
@@ -11,19 +16,27 @@ const max = 6
  * Make sure that there is only one top-level heading in the document by
  * adjusting headings depths accordingly.
  *
- * @template {Node} T
- * @param {T} tree
- * @returns {T}
+ * @template {Node} Tree
+ *   Node type.
+ * @param {Tree} tree
+ *   Tree to change.
+ * @returns {Tree}
+ *   Given, modified, `tree`.
  */
+// To do: next major: don’t return `tree`.
 export function normalizeHeadings(tree) {
-  /** @type {boolean|undefined} */
+  /** @type {Array<Heading>} */
+  const all = []
+  /** @type {boolean | undefined} */
   let multiple
-  /** @type {Heading|undefined} */
+  /** @type {Heading | undefined} */
   let first
-  /** @type {Heading|undefined} */
+  /** @type {Heading | undefined} */
   let title
 
   visit(tree, 'heading', (node) => {
+    all.push(node)
+
     if (!first) {
       first = node
     }
@@ -44,11 +57,13 @@ export function normalizeHeadings(tree) {
 
   // If there are multiple titles.
   if (multiple) {
-    visit(tree, 'heading', (node) => {
-      if (node !== title && node.depth < max) {
-        node.depth++
+    let index = -1
+    while (++index < all.length) {
+      const heading = all[index]
+      if (heading !== title && heading.depth < max) {
+        heading.depth++
       }
-    })
+    }
   }
 
   return tree