Refactor code-style

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

Author: wooorm

lib/index.js

@@ -3,8 +3,11 @@
  * @typedef {import('estree').Comment} EstreeComment
  *
  * @typedef State
+ *   Info passed around.
  * @property {Array<EstreeComment>} comments
+ *   Comments.
  * @property {number} index
+ *   Index of comment.
  *
  * @typedef Fields
  * @property {boolean} leading
@@ -16,9 +19,16 @@ const own = {}.hasOwnProperty
 /**
  * Attach semistandard estree comment nodes to the tree.
  *
- * @param {EstreeNode} tree
- * @param {Array<EstreeComment>} [comments]
+ * @template {EstreeNode} Tree
+ *   Node type.
+ * @param {Tree} tree
+ *   Tree to attach to.
+ * @param {Array<EstreeComment> | null | undefined} [comments]
+ *   List of comments.
+ * @returns {Tree}
+ *   Given tree.
  */
+// To do: next major: don’t return given `tree`.
 export function attachComments(tree, comments) {
   const list = (comments || []).concat().sort(compare)
   if (list.length > 0) walk(tree, {comments: list, index: 0})
@@ -29,7 +39,11 @@ export function attachComments(tree, comments) {
  * Attach semistandard estree comment nodes to the tree.
  *
  * @param {EstreeNode} node
+ *   Node.
  * @param {State} state
+ *   Info passed around.
+ * @returns {void}
+ *   Nothing.
  */
 function walk(node, state) {
   // Done, we can quit.
@@ -47,7 +61,7 @@ function walk(node, state) {
   // Find all children of `node`
   for (key in node) {
     if (own.call(node, key)) {
-      /** @type {EstreeNode|Array<EstreeNode>} */
+      /** @type {EstreeNode | Array<EstreeNode>} */
       // @ts-expect-error: indexable.
       const value = node[key]
 
@@ -96,9 +110,15 @@ function walk(node, state) {
 
 /**
  * @param {State} state
+ *   Info passed around.
  * @param {EstreeNode} node
+ *   Node.
  * @param {boolean} compareEnd
+ *   Whether to compare on the end (default is on start).
  * @param {Fields} fields
+ *   Fields.
+ * @returns {Array<EstreeComment>}
+ *   Slice from `state.comments`.
  */
 function slice(state, node, compareEnd, fields) {
   /** @type {Array<EstreeComment>} */
@@ -115,10 +135,16 @@ function slice(state, node, compareEnd, fields) {
 }
 
 /**
- * @param {EstreeNode|EstreeComment} left
- * @param {EstreeNode|EstreeComment} right
- * @param {boolean} [compareEnd]
+ * Sort two nodes (or comments).
+ *
+ * @param {EstreeNode | EstreeComment} left
+ *   A node.
+ * @param {EstreeNode | EstreeComment} right
+ *   The other node.
+ * @param {boolean | undefined} [compareEnd=false]
+ *   Compare on `end` of `right`, default is to compare on `start`.
  * @returns {number}
+ *   Sorting.
  */
 function compare(left, right, compareEnd) {
   const field = compareEnd ? 'end' : 'start'