Refactor code-style

*   Add more docs to JSDoc

Author: wooorm

lib/index.js

@@ -4,25 +4,35 @@
  * @typedef {import('mdast').HTML} HTML
  * @typedef {import('mdast-util-mdx-expression').MDXFlowExpression} MDXFlowExpression
  * @typedef {import('mdast-util-mdx-expression').MDXTextExpression} MDXTextExpression
- * @typedef {Root|Content} Node
- *
- * @typedef {string|number|boolean} MarkerParameterValue
- * @typedef {Record<string, MarkerParameterValue>} MarkerParameters
+ */
+
+/**
+ * @typedef {Root | Content} Node
  *
  * @typedef Mdx1CommentNode
  * @property {'comment'} type
  * @property {string} value
  *
+ * @typedef {string | number | boolean} MarkerParameterValue
+ *   Value.
+ *
+ *   If it looks like a number (to JavaScript), it’s cast as number.
+ *   The strings `true` and `false` are turned into their corresponding
+ *   booleans.
+ *   The empty string is also considered the `true` boolean.
+ * @typedef {Record<string, MarkerParameterValue>} MarkerParameters
+ *   Parameters.
+ *
  * @typedef Marker
  *   Comment marker.
  * @property {string} name
  *   Name of marker.
  * @property {string} attributes
  *   Value after name.
- * @property {MarkerParameters|null} parameters
+ * @property {MarkerParameters | null} parameters
  *   Parsed attributes, with decimal numbers, `true`, and `false` are casted to
  *   numbers and booleans.
- * @property {HTML|Mdx1CommentNode|MDXFlowExpression|MDXTextExpression} node
+ * @property {HTML | Mdx1CommentNode | MDXFlowExpression | MDXTextExpression} node
  *   Reference to given node.
  */
 
@@ -34,12 +44,13 @@ const markerExpression = new RegExp(
   '(\\s*<!--' + commentExpression.source + '-->\\s*)'
 )
 
+// To do: next major: replace `null` with `undefined` in API output.
 /**
  * Parse a comment marker.
  *
  * @param {unknown} value
  *   `Node` to parse.
- * @returns {Marker|null}
+ * @returns {Marker | null}
  *   Information, when applicable.
  */
 export function commentMarker(value) {
@@ -52,7 +63,7 @@ export function commentMarker(value) {
       value.type === 'mdxTextExpression')
   ) {
     let offset = 2
-    /** @type {RegExpMatchArray|null|undefined} */
+    /** @type {RegExpMatchArray | null | undefined} */
     let match
 
     // @ts-expect-error: MDX@1
@@ -87,10 +98,12 @@ export function commentMarker(value) {
 }
 
 /**
- * Parse `value` into an object.
+ * Parse a string of “attributes”.
  *
  * @param {string} value
- * @returns {MarkerParameters|null}
+ *   Attributes.
+ * @returns {MarkerParameters | null}
+ *   Parameters.
  */
 function parseParameters(value) {
   /** @type {MarkerParameters} */
@@ -111,18 +124,20 @@ function parseParameters(value) {
    * @param {string} $2
    * @param {string} $3
    * @param {string} $4
+   * @returns {string}
    */
   // eslint-disable-next-line max-params
   function replacer(_, $1, $2, $3, $4) {
     /** @type {MarkerParameterValue} */
     let value = $2 || $3 || $4 || ''
+    const number = Number(value)
 
     if (value === 'true' || value === '') {
       value = true
     } else if (value === 'false') {
       value = false
-    } else if (!Number.isNaN(Number(value))) {
-      value = Number(value)
+    } else if (!Number.isNaN(number)) {
+      value = number
     }
 
     parameters[$1] = value
@@ -132,8 +147,12 @@ function parseParameters(value) {
 }
 
 /**
+ * Check if something looks like a node.
+ *
  * @param {unknown} value
+ *   Thing.
  * @returns {value is Node}
+ *   It’s a node!
  */
 function isNode(value) {
   return Boolean(value && typeof value === 'object' && 'type' in value)

package.json

@@ -33,10 +33,10 @@
     "index.js"
   ],
   "dependencies": {
+    "@types/mdast": "^3.0.0",
     "mdast-util-mdx-expression": "^1.1.0"
   },
   "devDependencies": {
-    "@types/mdast": "^3.0.10",
     "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "prettier": "^2.0.0",