Refactor code-style

*   Add more docs to JSDoc

Author: wooorm

index.js

@@ -1,16 +1,31 @@
 /**
  * @typedef {import('hast').Root} Root
- * @typedef {Root['children'][number]|Root} Node
+ * @typedef {import('hast').Content} Content
+ */
+
+/**
+ * @typedef {Content | Root} Node
  */
 
 import {headingRank} from 'hast-util-heading-rank'
 import {visit} from 'unist-util-visit'
 
+// To do next major: don’t return node.
 /**
+ * Change the rank of all headings (`h1` to `h6`) in `tree`.
+ *
+ * Mutates the tree.
+ * Caps the rank so that shifting would not create invalid headings (so no `h0` or
+ * `h7`).
+ *
  * @template {Node} T
+ *   Node type.
  * @param {T} tree
+ *   Tree to change.
  * @param {number} shift
+ *   Non-null finite integer to use to shift ranks.
  * @returns {T}
+ *   Given, modified, tree.
  */
 export function shiftHeading(tree, shift) {
   if (

readme.md

@@ -128,6 +128,7 @@ There is no default export.
 ### `shiftHeading(tree, shift)`
 
 Change the rank of all headings (`h1` to `h6`) in `tree`.
+
 Mutates the tree.
 Caps the rank so that shifting would not create invalid headings (so no `h0` or
 `h7`).