Refactor code-style

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

Author: wooorm

lib/index.js

@@ -1,32 +1,53 @@
 /**
- * @typedef {import('mdast').Literal} Literal
- * @typedef {import('mdast').Parent} Parent
+ * @typedef {import('estree-jsx').Program} Program
+ *
  * @typedef {import('mdast-util-from-markdown').CompileContext} CompileContext
  * @typedef {import('mdast-util-from-markdown').Extension} FromMarkdownExtension
  * @typedef {import('mdast-util-from-markdown').Handle} FromMarkdownHandle
  * @typedef {import('mdast-util-from-markdown').Token} Token
  * @typedef {import('mdast-util-from-markdown').OnEnterError} OnEnterError
  * @typedef {import('mdast-util-from-markdown').OnExitError} OnExitError
+ *
  * @typedef {import('mdast-util-to-markdown').Options} ToMarkdownExtension
  * @typedef {import('mdast-util-to-markdown').Handle} ToMarkdownHandle
  * @typedef {import('mdast-util-to-markdown').Map} ToMarkdownMap
- * @typedef {import('estree-jsx').Program} Program
+ *
  * @typedef {import('./complex-types.js').MdxJsxAttributeValueExpression} MdxJsxAttributeValueExpression
  * @typedef {import('./complex-types.js').MdxJsxAttribute} MdxJsxAttribute
  * @typedef {import('./complex-types.js').MdxJsxExpressionAttribute} MdxJsxExpressionAttribute
  * @typedef {import('./complex-types.js').MdxJsxFlowElement} MdxJsxFlowElement
  * @typedef {import('./complex-types.js').MdxJsxTextElement} MdxJsxTextElement
- * @typedef {{name: string|null, attributes: (MdxJsxAttribute|MdxJsxExpressionAttribute)[], close?: boolean, selfClosing?: boolean, start: Token['start'], end: Token['start']}} Tag
+ */
+
+/**
+ * @typedef Tag
+ *   Single tag.
+ * @property {string | undefined} name
+ *   Name of tag, or `undefined` for fragment.
+ *
+ *   > 👉 **Note**: `null` is used in the AST for fragments, as it serializes in
+ *   > JSON.
+ * @property {Array<MdxJsxAttribute | MdxJsxExpressionAttribute>} attributes
+ *   Attributes.
+ * @property {boolean} close
+ *   Whether the tag is closing (`</x>`).
+ * @property {boolean} selfClosing
+ *   Whether the tag is self-closing (`<x/>`).
+ * @property {Token['start']} start
+ *   Start point.
+ * @property {Token['start']} end
+ *   End point.
  *
  * @typedef ToMarkdownOptions
- * @property {'"'|"'"} [quote='"']
+ *   Configuration.
+ * @property {'"' | "'" | null | undefined} [quote='"']
  *   Preferred quote to use around attribute values.
- * @property {boolean} [quoteSmart=false]
+ * @property {boolean | null | undefined} [quoteSmart=false]
  *   Use the other quote if that results in less bytes.
- * @property {boolean} [tightSelfClosing=false]
+ * @property {boolean | null | undefined} [tightSelfClosing=false]
  *   Do not use an extra space when closing self-closing elements: `<img/>`
  *   instead of `<img />`.
- * @property {number} [printWidth=Infinity]
+ * @property {number | null | undefined} [printWidth=Infinity]
  *   Specify the line length that the printer will wrap on.
  *   This is not a hard maximum width: things will be printed longer and
  *   shorter.
@@ -45,7 +66,17 @@ import {containerPhrasing} from 'mdast-util-to-markdown/lib/util/container-phras
 import {indentLines} from 'mdast-util-to-markdown/lib/util/indent-lines.js'
 import {track} from 'mdast-util-to-markdown/lib/util/track.js'
 
-/** @return {FromMarkdownExtension} */
+// To do: next major: use `state`, use utilities from state, rename `safeOptions` to `info`.
+
+/**
+ * Create an extension for `mdast-util-from-markdown` to enable MDX JSX.
+ *
+ * @returns {FromMarkdownExtension}
+ *   Extension for `mdast-util-from-markdown` to enable MDX JSX.
+ *
+ *   When using the syntax extension with `addResult`, nodes will have a
+ *   `data.estree` field set to an ESTree `Program` node.
+ */
 export function mdxJsxFromMarkdown() {
   return {
     canContainEols: ['mdxJsxTextElement'],
@@ -124,7 +155,14 @@ export function mdxJsxFromMarkdown() {
    */
   function enterMdxJsxTag(token) {
     /** @type {Tag} */
-    const tag = {name: null, attributes: [], start: token.start, end: token.end}
+    const tag = {
+      name: undefined,
+      attributes: [],
+      close: false,
+      selfClosing: false,
+      start: token.start,
+      end: token.end
+    }
     // @ts-expect-error: to do: register.
     if (!this.getData('mdxJsxTagStack')) this.setData('mdxJsxTagStack', [])
     // @ts-expect-error: to do: register.
@@ -138,7 +176,7 @@ export function mdxJsxFromMarkdown() {
    */
   function enterMdxJsxTagClosingMarker(token) {
     // @ts-expect-error: to do: register.
-    const stack = /** @type {Tag[]} */ (this.getData('mdxJsxTagStack'))
+    const stack = /** @type {Array<Tag>} */ (this.getData('mdxJsxTagStack'))
 
     if (stack.length === 0) {
       throw new VFileMessage(
@@ -256,7 +294,7 @@ export function mdxJsxFromMarkdown() {
     const tail = /** @type {MdxJsxExpressionAttribute} */ (
       tag.attributes[tag.attributes.length - 1]
     )
-    /** @type {Program|undefined} */
+    /** @type {Program | undefined} */
     // @ts-expect-error: custom.
     const estree = token.estree
 
@@ -318,7 +356,7 @@ export function mdxJsxFromMarkdown() {
     )
     /** @type {MdxJsxAttributeValueExpression} */
     const node = {type: 'mdxJsxAttributeValueExpression', value: this.resume()}
-    /** @type {Program|undefined} */
+    /** @type {Program | undefined} */
     // @ts-expect-error: custom.
     const estree = token.estree
 
@@ -348,7 +386,7 @@ export function mdxJsxFromMarkdown() {
     // @ts-expect-error: to do: register.
     const tag = /** @type {Tag} */ (this.getData('mdxJsxTag'))
     // @ts-expect-error: to do: register.
-    const stack = /** @type {Tag[]} */ (this.getData('mdxJsxTagStack'))
+    const stack = /** @type {Array<Tag>} */ (this.getData('mdxJsxTagStack'))
     const tail = stack[stack.length - 1]
 
     if (tag.close && tail.name !== tag.name) {
@@ -377,7 +415,7 @@ export function mdxJsxFromMarkdown() {
             token.type === 'mdxJsxTextTag'
               ? 'mdxJsxTextElement'
               : 'mdxJsxFlowElement',
-          name: tag.name,
+          name: tag.name || null,
           attributes: tag.attributes,
           children: []
         },
@@ -454,17 +492,19 @@ export function mdxJsxFromMarkdown() {
 }
 
 /**
- * @param {ToMarkdownOptions} [options={}]
- *   Configuration (optional).
+ * Create an extension for `mdast-util-to-markdown` to enable MDX JSX.
+ *
+ * @param {ToMarkdownOptions | null | undefined} [options]
+ *   Configuration.
  * @returns {ToMarkdownExtension}
+ *   Extension for `mdast-util-to-markdown` to enable MDX JSX.
  */
-export function mdxJsxToMarkdown(options = {}) {
-  const {
-    quote = '"',
-    quoteSmart,
-    tightSelfClosing,
-    printWidth = Number.POSITIVE_INFINITY
-  } = options
+export function mdxJsxToMarkdown(options) {
+  const options_ = options || {}
+  const quote = options_.quote || '"'
+  const quoteSmart = options_.quoteSmart || false
+  const tightSelfClosing = options_.tightSelfClosing || false
+  const printWidth = options_.printWidth || Number.POSITIVE_INFINITY
   const alternative = quote === '"' ? "'" : '"'
 
   if (quote !== '"' && quote !== "'") {
@@ -486,13 +526,15 @@ export function mdxJsxToMarkdown(options = {}) {
       {character: '<', inConstruct: ['phrasing']},
       {atBreak: true, character: '<'}
     ],
+    // Always generate fenced code (never indented code).
     fences: true,
+    // Always generate links with resources (never autolinks).
     resourceLink: true
   }
 
   /**
    * @type {ToMarkdownHandle}
-   * @param {MdxJsxFlowElement|MdxJsxTextElement} node
+   * @param {MdxJsxFlowElement | MdxJsxTextElement} node
    */
   // eslint-disable-next-line complexity
   function mdxElement(node, _, context, safeOptions) {