Refactor code-style

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

Author: wooorm

Diff for: lib/index.js

@@ -1,42 +1,61 @@
 /**
- * @typedef {import('unist').Parent} Parent
- * @typedef {import('mdast').Root|import('mdast').Content} Node
+ * @typedef {import('unist').Parent} UnistParent
+ * @typedef {import('mdast').Content} Content
  * @typedef {import('mdast').Heading} Heading
+ * @typedef {import('mdast').Root} Root
+ */
+
+/**
+ * @typedef {Content | Root} Node
+ * @typedef {Extract<Node, UnistParent>} Parent
  *
- * @typedef {(value: string, node: Heading) => boolean} TestFunction
- *   Function called for each heading with its content and `node` itself check
- *   if it’s the one to look for.
+ * @callback TestFunction
+ *   Function called with headings to check if it’s the one to look for.
+ * @param {string} value
+ *   Plain-text heading.
+ * @param {Heading} node
+ *   Heading node.
+ * @returns {boolean}
+ *   Whether this is the heading that is searched for.
  *
- * @typedef {string|RegExp|TestFunction} Test
+ * @typedef {string | RegExp | TestFunction} Test
+ *   A test.
  *
  * @typedef Options
  *   Configuration (optional).
  * @property {Test} test
  *   Heading to look for.
+ *
  *   When `string`, wrapped in `new RegExp('^(' + value + ')$', 'i')`;
- *   when `RegExp`, wrapped in `function (value) {expression.test(value)}`
- * @property {boolean} [ignoreFinalDefinitions=false]
+ *   when `RegExp`, wrapped in `(value) => expression.test(value)`
+ * @property {boolean | null | undefined} [ignoreFinalDefinitions=false]
  *   Ignore final definitions otherwise in the section.
  *
  * @typedef ZoneInfo
  *   Extra info.
- * @property {Parent|null} parent
+ * @property {Parent | null} parent
  *   Parent of the range.
  * @property {number} start
  *   index of `start` in `parent`
- * @property {number} end
+ * @property {number | null} end
  *   index of `end` in `parent`
  *
  * @callback Handler
  *   Callback called when a range is found.
- * @param {Heading|undefined} start
- *   Start of range.
+ * @param {Heading} start
+ *   Start of range (a heading node matching `test`).
  * @param {Array<Node>} between
  *   Nodes between `start` and `end`.
- * @param {Node|undefined} end
+ * @param {Node | undefined} end
  *   End of range, if any.
  * @param {ZoneInfo} scope
  *   Extra info.
+ * @returns {Array<Node | null | undefined> | null | undefined | void}
+ *   Results.
+ *
+ *   If nothing is returned, nothing will be changed.
+ *   If an array of nodes (can include `null` and `undefined`) is returned, the
+ *   original section will be replaced by those nodes.
  */
 
 import {toString} from 'mdast-util-to-string'
@@ -47,24 +66,29 @@ import {toString} from 'mdast-util-to-string'
  *
  * A “section” is a heading that passes `test`, until the next heading of the
  * same or lower depth, or the end of the document.
+ *
  * If `ignoreFinalDefinitions: true`, final definitions “in” the section are
  * excluded.
  *
  * @param {Node} tree
- * @param {Test|Options} options
+ *   Tree to change.
+ * @param {Test | Options} options
+ *   Configuration.
  * @param {Handler} handler
+ *   Handle a range.
+ * @returns {void}
+ *   Nothing.
  */
 // eslint-disable-next-line complexity
 export function headingRange(tree, options, handler) {
   let test = options
   /** @type {Array<Node>} */
   const children = 'children' in tree ? tree.children : []
-  /** @type {boolean|undefined} */
-  let ignoreFinalDefinitions
+  let ignoreFinalDefinitions = false
 
   // Object, not regex.
   if (test && typeof test === 'object' && !('exec' in test)) {
-    ignoreFinalDefinitions = test.ignoreFinalDefinitions
+    ignoreFinalDefinitions = test.ignoreFinalDefinitions === true
     test = test.test
   }
 
@@ -87,11 +111,11 @@ export function headingRange(tree, options, handler) {
   }
 
   let index = -1
-  /** @type {number|undefined} */
+  /** @type {number | undefined} */
   let start
-  /** @type {number|undefined} */
+  /** @type {number | undefined} */
   let end
-  /** @type {number|undefined} */
+  /** @type {number|  undefined} */
   let depth
 
   // Find the range.
@@ -124,14 +148,18 @@ export function headingRange(tree, options, handler) {
       }
     }
 
-    /** @type {Array<Node>} */
-    const nodes = handler(
-      // @ts-expect-error `start` points to a heading.
-      children[start],
-      children.slice(start + 1, end),
-      children[end],
-      {parent: tree, start, end: children[end] ? end : null}
-    )
+    /** @type {Heading} */
+    // @ts-expect-error `start` points to a heading.
+    const head = children[start]
+    /** @type {Parent} */
+    // @ts-expect-error always a parent, or we don’t come here.
+    const parent = tree
+
+    const nodes = handler(head, children.slice(start + 1, end), children[end], {
+      parent,
+      start,
+      end: children[end] ? end : null
+    })
 
     if (nodes) {
       // Ensure no empty nodes are inserted.
@@ -141,7 +169,8 @@ export function headingRange(tree, options, handler) {
       let index = -1
 
       while (++index < nodes.length) {
-        if (nodes[index]) result.push(nodes[index])
+        const node = nodes[index]
+        if (node) result.push(node)
       }
 
       children.splice(start, end - start + 1, ...result)
@@ -151,17 +180,16 @@ export function headingRange(tree, options, handler) {
 
 /**
  * Wrap an expression into an assertion function.
+ *
  * @param {RegExp} expression
- * @returns {(value: string) => boolean}
+ *   Test expression.
+ * @returns {TestFunction}
+ *   Test function.
  */
 function wrapExpression(expression) {
   return assertion
 
-  /**
-   * Assert `value` matches the bound `expression`.
-   * @param {string} value
-   * @returns {boolean}
-   */
+  /** @type {TestFunction} */
   function assertion(value) {
     return expression.test(value)
   }

Diff for: package.json

@@ -41,8 +41,9 @@
   "devDependencies": {
     "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
+    "mdast-util-from-markdown": "^1.0.0",
+    "mdast-util-to-markdown": "^1.0.0",
     "prettier": "^2.0.0",
-    "remark": "^14.0.0",
     "remark-cli": "^11.0.0",
     "remark-preset-wooorm": "^9.0.0",
     "tape": "^5.0.0",