Refactor code-style

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

Author: wooorm

lib/index.js

@@ -1,29 +1,46 @@
 /**
- * @typedef {import('mdast').AlignType} AlignType
  * @typedef {import('mdast').Table} Table
  * @typedef {import('mdast').TableRow} TableRow
  * @typedef {import('mdast').TableCell} TableCell
  * @typedef {import('mdast').InlineCode} InlineCode
+ *
  * @typedef {import('markdown-table').MarkdownTableOptions} MarkdownTableOptions
+ *
  * @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-to-markdown').Options} ToMarkdownExtension
  * @typedef {import('mdast-util-to-markdown').Handle} ToMarkdownHandle
  * @typedef {import('mdast-util-to-markdown').Context} ToMarkdownContext
  * @typedef {import('mdast-util-to-markdown').SafeOptions} SafeOptions
- *
+ */
+
+/**
  * @typedef Options
- * @property {boolean} [tableCellPadding=true]
- * @property {boolean} [tablePipeAlign=true]
- * @property {MarkdownTableOptions['stringLength']} [stringLength]
+ *   Configuration.
+ * @property {boolean | null | undefined} [tableCellPadding=true]
+ *   Whether to add a space of padding between delimiters and cells.
+ * @property {boolean | null | undefined} [tablePipeAlign=true]
+ *   Whether to align the delimiters.
+ * @property {MarkdownTableOptions['stringLength'] | null | undefined} [stringLength]
+ *   Function to detect the length of table cell content, used when aligning
+ *   the delimiters between cells
  */
 
 import {containerPhrasing} from 'mdast-util-to-markdown/lib/util/container-phrasing.js'
 import {inlineCode} from 'mdast-util-to-markdown/lib/handle/inline-code.js'
 import {markdownTable} from 'markdown-table'
 
-/** @type {FromMarkdownExtension} */
+// To do: next major: use `state` and `state` utilities from `mdast-util-to-markdown`.
+// To do: next major: use `defaultHandlers.inlineCode`.
+// To do: next major: expose functions.
+
+/**
+ * Extension for `mdast-util-from-markdown` to enable GFM tables.
+ *
+ * @type {FromMarkdownExtension}
+ */
 export const gfmTableFromMarkdown = {
   enter: {
     table: enterTable,
@@ -45,7 +62,7 @@ export const gfmTableFromMarkdown = {
  * @type {FromMarkdownHandle}
  */
 function enterTable(token) {
-  /** @type {Array<'left'|'right'|'center'|'none'>} */
+  /** @type {Array<'left' | 'right' | 'center' | 'none'>} */
   // @ts-expect-error: `align` is custom.
   const align = token._align
   this.enter(
@@ -121,8 +138,13 @@ function replace($0, $1) {
 }
 
 /**
- * @param {Options} [options]
+ * Create an extension for `mdast-util-to-markdown` to enable GFM tables in
+ * markdown.
+ *
+ * @param {Options | null | undefined} [options]
+ *   Configuration.
  * @returns {ToMarkdownExtension}
+ *   Extension for `mdast-util-to-markdown` to enable GFM tables.
  */
 export function gfmTableToMarkdown(options) {
   const settings = options || {}
@@ -165,7 +187,6 @@ export function gfmTableToMarkdown(options) {
   function handleTable(node, _, context, safeOptions) {
     return serializeData(
       handleTableAsData(node, context, safeOptions),
-      // @ts-expect-error: fixed in `markdown-table@3.0.1`.
       node.align
     )
   }
@@ -180,8 +201,8 @@ export function gfmTableToMarkdown(options) {
    */
   function handleTableRow(node, _, context, safeOptions) {
     const row = handleTableRowAsData(node, context, safeOptions)
-    // `markdown-table` will always add an align row
     const value = serializeData([row])
+    // `markdown-table` will always add an align row
     return value.slice(0, value.indexOf('\n'))
   }
 
@@ -204,13 +225,16 @@ export function gfmTableToMarkdown(options) {
 
   /**
    * @param {Array<Array<string>>} matrix
-   * @param {Array<string>} [align]
+   * @param {Array<string | null | undefined> | null | undefined} [align]
    */
   function serializeData(matrix, align) {
     return markdownTable(matrix, {
       align,
+      // @ts-expect-error: `markdown-table` types should support `null`.
       alignDelimiters,
+      // @ts-expect-error: `markdown-table` types should support `null`.
       padding,
+      // @ts-expect-error: `markdown-table` types should support `null`.
       stringLength
     })
   }