Refactor JSDoc

Author: wooorm

lib/index.js

@@ -1,11 +1,16 @@
 /**
- * @typedef {import('vfile').VFile} VFile
- * @typedef {import('nlcst').Parent} Parent
  * @typedef {import('nlcst').Content} Content
- * @typedef {import('nlcst').SentenceContent} SentenceContent
- * @typedef {import('nlcst').Root} Root
  * @typedef {import('nlcst').Paragraph} Paragraph
+ * @typedef {import('nlcst').Parent} Parent
+ * @typedef {import('nlcst').Root} Root
  * @typedef {import('nlcst').Sentence} Sentence
+ * @typedef {import('nlcst').SentenceContent} SentenceContent
+ * @typedef {import('vfile').VFile} VFile
+ */
+
+/**
+ * @typedef {Content | Root} Nodes
+ * @typedef {Extract<Nodes, Parent>} Parents
  */
 
 /**
@@ -60,6 +65,7 @@ export class ParseLatin {
   constructor(doc, file) {
     const value = file || doc
 
+    // To do: next major: use `undefined`.
     /** @type {string | null} */
     this.doc = value ? String(value) : null
 
@@ -296,19 +302,19 @@ ParseLatin.prototype.tokenizeRootPlugins = [
 /**
  * A function that splits one node into several nodes.
  *
- * @template {Parent} TheNode
+ * @template {Parents} Node
  *   Node type.
- * @param {TheNode} node
+ * @param {Node} node
  *   Node to split.
  * @param {RegExp} expression
  *   Split on this regex.
  * @param {Content['type']} childType
  *   Split this node type.
- * @returns {Array<TheNode>}
+ * @returns {Array<Node>}
  *   The given node, split into several nodes.
  */
 function splitNode(node, childType, expression) {
-  /** @type {Array<TheNode>} */
+  /** @type {Array<Node>} */
   const result = []
   let index = -1
   let start = 0
@@ -320,7 +326,7 @@ function splitNode(node, childType, expression) {
       index === node.children.length - 1 ||
       (token.type === childType && expression.test(toString(token)))
     ) {
-      /** @type {TheNode} */
+      /** @type {Node} */
       // @ts-expect-error: fine
       const parent = {
         type: node.type,

lib/plugin/make-final-white-space-siblings.js

@@ -1,6 +1,6 @@
 /**
- * @typedef {import('nlcst').Root} Root
  * @typedef {import('nlcst').Paragraph} Paragraph
+ * @typedef {import('nlcst').Root} Root
  */
 
 import {modifyChildren} from 'unist-util-modify-children'

lib/plugin/make-initial-white-space-siblings.js

@@ -1,6 +1,6 @@
 /**
- * @typedef {import('nlcst').Root} Root
  * @typedef {import('nlcst').Paragraph} Paragraph
+ * @typedef {import('nlcst').Root} Root
  */
 
 import {visitChildren} from 'unist-util-visit-children'

lib/plugin/merge-inner-word-slash.js

@@ -1,7 +1,7 @@
 /**
+ * @typedef {import('nlcst').Sentence} Sentence
  * @typedef {import('nlcst').SentenceContent} SentenceContent
  * @typedef {import('nlcst').WordContent} WordContent
- * @typedef {import('nlcst').Sentence} Sentence
  */
 
 import {toString} from 'nlcst-to-string'

lib/plugin/patch-position.js

@@ -1,8 +1,9 @@
 /**
- * @typedef {import('unist').Node} Node
- * @typedef {import('nlcst').Sentence} Sentence
  * @typedef {import('nlcst').Paragraph} Paragraph
+ * @typedef {import('nlcst').Sentence} Sentence
  * @typedef {import('nlcst').Root} Root
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('unist').Position} Position
  */
 
 import {visitChildren} from 'unist-util-visit-children'
@@ -22,7 +23,6 @@ export const patchPosition = visitChildren(
       (!node.position || !node.position.start)
     ) {
       patch(node)
-      // @ts-expect-error: we just set it.
       node.position.start = child.position.start
     }
 
@@ -32,18 +32,18 @@ export const patchPosition = visitChildren(
       (!node.position || !node.position.end)
     ) {
       patch(node)
-      // @ts-expect-error: we just set it.
       node.position.end = child.position.end
     }
   }
 )
 
 /**
  * @param {Node} node
+ * @returns {asserts node is Node & {position: Position}}
  */
 function patch(node) {
   if (!node.position) {
-    // @ts-expect-error: fine.
+    // @ts-expect-error: fine, we’ll fill it later.
     node.position = {}
   }
 }

lib/plugin/remove-empty-nodes.js

@@ -1,14 +1,14 @@
 /**
- * @typedef {import('nlcst').Root} Root
  * @typedef {import('nlcst').Paragraph} Paragraph
+ * @typedef {import('nlcst').Root} Root
  */
 
 import {modifyChildren} from 'unist-util-modify-children'
 
 // Remove empty children.
 export const removeEmptyNodes = modifyChildren(
   /**
-   * @type {import('unist-util-modify-children').Modifier<Root | Paragraph>}
+   * @type {import('unist-util-modify-children').Modifier<Paragraph | Root>}
    */
 
   function (child, index, parent) {

test/index.js

@@ -1235,12 +1235,12 @@ test('Abbreviations: Initialisms', async function (t) {
  *
  * @param {string} name
  * @param {string} doc
- * @param {'parse' | 'tokenizeParagraph' | 'tokenizeRoot' | 'tokenizeSentence'} [method='parse']
- * @returns {Promise<void>}
+ * @param {'parse' | 'tokenizeParagraph' | 'tokenizeRoot' | 'tokenizeSentence' | undefined} [method='parse']
+ * @returns {Promise<undefined>}
  */
 async function describeFixture(name, doc, method = 'parse') {
   const nlcstA = latin[method](doc)
-  /** @type {Root | Content} */
+  /** @type {Content | Root} */
   const fixture = JSON.parse(
     String(await fs.readFile(path.join('test', 'fixture', name + '.json')))
   )