Refactor code-style

Author: wooorm

lib/index.js

@@ -1,24 +1,21 @@
 /**
- * @typedef {import('unist').Point} Point
- *
  * @typedef {import('nlcst').Root} NlcstRoot
  * @typedef {import('nlcst').Paragraph} NlcstParagraph
- * @typedef {import('nlcst').WhiteSpace} NlcstWhiteSpace
  * @typedef {import('nlcst').Sentence} NlcstSentence
- * @typedef {import('nlcst').Source} NlcstSource
  * @typedef {import('nlcst').Content} NlcstContent
  * @typedef {import('nlcst').SentenceContent} NlcstSentenceContent
- * @typedef {NlcstRoot|NlcstContent} NlcstNode
- * @typedef {Extract<NlcstNode, import('unist').Parent>} NlcstParent
- *
  * @typedef {import('hast').Root} HastRoot
  * @typedef {import('hast').Element} HastElement
  * @typedef {import('hast').Content} HastContent
  * @typedef {import('hast').ElementContent} HastElementContent
- * @typedef {HastRoot|HastContent} HastNode
- * @typedef {Extract<HastNode, import('unist').Parent>} HastParent
- *
  * @typedef {import('vfile').VFile} VFile
+ */
+
+/**
+ * @typedef {NlcstRoot | NlcstContent} NlcstNode
+ * @typedef {Extract<NlcstNode, import('unist').Parent>} NlcstParent
+ * @typedef {HastRoot | HastContent} HastNode
+ *
  *
  * @typedef {{
  *   tokenizeSentencePlugins: Array<(node: NlcstSentence) => void>,
@@ -81,12 +78,16 @@ const flowAccepting = convertElement([
 const terminalMarker = /^([!.?\u2026\u203D]+)$/
 
 /**
- * Transform `tree` to nlcst.
+ * Turn a hast tree into an nlcst tree.
  *
  * @param {HastNode} tree
+ *   hast tree to transform.
  * @param {VFile} file
- * @param {ParserInstance|ParserConstructor} Parser
+ *   Virtual file.
+ * @param {ParserInstance | ParserConstructor} Parser
+ *   Parser to use.
  * @returns {NlcstRoot}
+ *   nlcst tree.
  */
 export function toNlcst(tree, file, Parser) {
   // Warn for invalid parameters.
@@ -122,7 +123,12 @@ export function toNlcst(tree, file, Parser) {
   }
 
   /**
+   * Transform a hast node.
+   *
    * @param {HastNode} node
+   *   hast node.
+   * @returns {void}
+   *   Nothing.
    */
   function find(node) {
     if (node.type === 'root') {
@@ -132,7 +138,8 @@ export function toNlcst(tree, file, Parser) {
         // Explicit paragraph.
         add(node)
       } else if (flowAccepting(node)) {
-        // Slightly simplified version of: <https://html.spec.whatwg.org/#paragraphs>.
+        // Slightly simplified version of:
+        // <https://html.spec.whatwg.org/multipage/dom.html#paragraphs>.
         implicit(flattenAll(node.children))
       } else {
         // Dig deeper.
@@ -142,7 +149,12 @@ export function toNlcst(tree, file, Parser) {
   }
 
   /**
+   * Transform hast children.
+   *
    * @param {Array<HastContent>} children
+   *   hast children.
+   * @returns {void}
+   *   Nothing.
    */
   function findAll(children) {
     let index = -1
@@ -153,8 +165,12 @@ export function toNlcst(tree, file, Parser) {
   }
 
   /**
+   * Flatten hast children: this unravels `a`, `ins`, `del`, and `map` elements.
+   *
    * @param {Array<HastElementContent>} children
+   *   Children.
    * @returns {Array<HastElementContent>}
+   *   Flattened children.
    */
   function flattenAll(children) {
     /** @type {Array<HastElementContent>} */
@@ -182,7 +198,12 @@ export function toNlcst(tree, file, Parser) {
   }
 
   /**
-   * @param {HastElementContent|Array<HastElementContent>} node
+   * Add one or more nodes.
+   *
+   * @param {HastElementContent | Array<HastElementContent>} node
+   *   hast node.
+   * @returns {void}
+   *   Nothing.
    */
   function add(node) {
     /** @type {Array<NlcstSentenceContent> | undefined} */
@@ -220,12 +241,19 @@ export function toNlcst(tree, file, Parser) {
   }
 
   /**
+   * Handle implicit paragraphs.
+   *
+   * See: <https://html.spec.whatwg.org/multipage/dom.html#paragraphs>.
+   *
    * @param {Array<HastElementContent>} children
+   *   hast nodes.
+   * @returns {void}
+   *   Nothing.
    */
   function implicit(children) {
     let index = -1
     let start = -1
-    /** @type {boolean|undefined} */
+    /** @type {boolean | undefined} */
     let viable
 
     while (++index <= children.length) {
@@ -254,15 +282,17 @@ export function toNlcst(tree, file, Parser) {
   }
 
   /**
-   * Convert `node` (hast) to nlcst.
+   * Turn a hast node into nlcst nodes.
    *
    * @param {HastContent} node
-   * @returns {Array<NlcstSentenceContent>|undefined}
+   *   hast node.
+   * @returns {Array<NlcstSentenceContent> | undefined}
+   *   nlcst sentence content.
    */
   function one(node) {
-    /** @type {Array<NlcstSentenceContent>|undefined} */
+    /** @type {Array<NlcstSentenceContent> | undefined} */
     let replacement
-    /** @type {boolean|undefined} */
+    /** @type {boolean | undefined} */
     let change
 
     if (node.type === 'text') {
@@ -283,41 +313,52 @@ export function toNlcst(tree, file, Parser) {
       }
     }
 
-    return change && replacement
-      ? patch(replacement, loc, loc.toOffset(pointStart(node)))
-      : replacement
+    if (change && replacement) {
+      patch(replacement, loc, loc.toOffset(pointStart(node)))
+    }
+
+    return replacement
   }
 
   /**
-   * Convert all `children` (hast) to nlcst.
+   * Turn hast nodes into nlcst nodes.
    *
-   * @param {Array<HastContent>} children
-   * @returns {Array<NlcstSentenceContent>}
+   * @param {Array<HastContent>} nodes
+   *   hast nodes.
+   * @returns {Array<NlcstSentenceContent> | undefined}
+   *   nlcst sentence content.
    */
-  function all(children) {
+  function all(nodes) {
     /** @type {Array<NlcstSentenceContent>} */
     const results = []
     let index = -1
 
-    while (++index < children.length) {
-      results.push(...(one(children[index]) || []))
+    while (++index < nodes.length) {
+      const result = one(nodes[index])
+      if (result) {
+        results.push(...result)
+      }
     }
 
     return results
   }
 
   /**
    * Patch a position on each node in `nodes`.
+   *
    * `offset` is the offset in `file` this run of content starts at.
    *
    * Note that nlcst nodes are concrete, meaning that their starting and ending
    * positions can be inferred from their content.
    *
-   * @template {Array<NlcstContent>} T
-   * @param {T} nodes
+   * @param {Array<NlcstContent>} nodes
+   *   Nodes to patch.
    * @param {ReturnType<location>} location
+   *   Location info.
    * @param {number} offset
-   * @returns {T}
+   *   Current offset.
+   * @returns {void}
+   *   Nothing.
    */
   function patch(nodes, location, offset) {
     let index = -1
@@ -339,22 +380,28 @@ export function toNlcst(tree, file, Parser) {
 
       start = end
     }
-
-    return nodes
   }
 }
 
 /**
+ * Check if an element has a `data-nlcst` attribute set to `source`.
+ *
  * @param {HastElement} node
+ *   Element.
  * @returns {boolean}
+ *   Whether `node` has a `data-nlcst` attribute set to `source`.
  */
 function dataNlcstSourced(node) {
   return Boolean(node.properties && node.properties.dataNlcst === 'source')
 }
 
 /**
+ * Check if an element has a `data-nlcst` attribute set to `ignore`.
+ *
  * @param {HastElement} node
+ *   Element.
  * @returns {boolean}
+ *   Whether `node` has a `data-nlcst` attribute set to `ignore`.
  */
 function dataNlcstIgnore(node) {
   return Boolean(node.properties && node.properties.dataNlcst === 'ignore')