Add improved docs

lib/handlers/index.js

@@ -39,13 +39,23 @@ import {text} from './text.js'
 import {textarea} from './textarea.js'
 import {wbr} from './wbr.js'
 
+/**
+ * Default handlers for nodes.
+ *
+ * Each key is a node type, each value is a `NodeHandler`.
+ */
 export const nodeHandlers = {
   root,
   text,
   comment,
   doctype: ignore
 }
 
+/**
+ * Default handlers for elements.
+ *
+ * Each key is an element name, each value is a `Handler`.
+ */
 export const handlers = {
   applet: ignore,
   area: ignore,

lib/state.js

@@ -6,7 +6,6 @@
  * @typedef {import('mdast').Content} MdastContent
  * @typedef {import('mdast').BlockContent} MdastBlockContent
  * @typedef {import('mdast').DefinitionContent} MdastDefinitionContent
- * @typedef {import('mdast').PhrasingContent} MdastPhrasingContent
  * @typedef {import('./types.js').Options} Options
  * @typedef {import('./types.js').Handle} Handle
  * @typedef {import('./types.js').NodeHandle} NodeHandle
@@ -21,12 +20,14 @@
  *
  * @typedef State
  *   Info passed around about the current state.
- * @property {PatchPosition} patch
+ * @property {Patch} patch
  *   Copy a node’s positional info.
+ * @property {One} one
+ *   Transform a hast node to mdast.
  * @property {All} all
  *   Transform the children of a hast parent to mdast.
  * @property {ToFlow} toFlow
- *   Transform the children of a hast parent to mdast flow content.
+ *   Transform a list of mdast nodes to flow.
  * @property {<ChildType extends MdastNode, ParentType extends MdastParent & {'children': Array<ChildType>}>(nodes: Array<MdastContent>, build: (() => ParentType)) => Array<ParentType>} toSpecificContent
  *   Turn arbitrary content into a list of a particular node type.
  *
@@ -35,8 +36,6 @@
  *   in this example, when non-items are found, they will be queued, and
  *   inserted into an adjacent item.
  *   When no actual items exist, one will be made with `build`.
- * @property {One} one
- *   Transform a hast node to mdast.
  * @property {Resolve} resolve
  *   Resolve a URL relative to a base.
  * @property {Options} options
@@ -56,11 +55,11 @@
  * @property {number} qNesting
  *   Non-negative finite integer representing how deep we’re in `<q>`s.
  *
- * @callback PatchPosition
+ * @callback Patch
  *   Copy a node’s positional info.
- * @param {Node} origin
+ * @param {Node} from
  *   hast node to copy from.
- * @param {MdastNode} node
+ * @param {MdastNode} to
  *   mdast node to copy into.
  * @returns {void}
  *   Nothing.
@@ -73,7 +72,7 @@
  *   mdast children.
  *
  * @callback ToFlow
- *   Transform the children of a hast parent to mdast, as flow content.
+ *   Transform a list of mdast nodes to flow.
  * @param {Array<MdastContent>} nodes
  *   mdast nodes.
  * @returns {Array<MdastFlowContent>}
@@ -233,7 +232,7 @@ function all(parent) {
 }
 
 /**
- * Transform the children of a hast parent to mdast.
+ * Transform a list of mdast nodes to flow.
  *
  * @this {State}
  *   Info passed around about the current state.
@@ -247,29 +246,7 @@ function toFlow(nodes) {
 }
 
 /**
- * @this {State}
- *   Info passed around about the current state.
- * @param {string | null | undefined} url
- *   Possible URL value.
- * @returns {string}
- *   URL, resolved to a `base` element, if any.
- */
-function resolve(url) {
-  const base = this.frozenBaseUrl
-
-  if (url === null || url === undefined) {
-    return ''
-  }
-
-  if (base) {
-    return String(new URL(url, base))
-  }
-
-  return url
-}
-
-/**
- * Turn arbitrary content into a list of a particular node type.
+ * Turn arbitrary content into a particular node type.
  *
  * This is useful for example for lists, which must have list items as content.
  * in this example, when non-items are found, they will be queued, and
@@ -335,3 +312,25 @@ function toSpecificContent(nodes, build) {
     return node.type === reference.type
   }
 }
+
+/**
+ * @this {State}
+ *   Info passed around about the current state.
+ * @param {string | null | undefined} url
+ *   Possible URL value.
+ * @returns {string}
+ *   URL, resolved to a `base` element, if any.
+ */
+function resolve(url) {
+  const base = this.frozenBaseUrl
+
+  if (url === null || url === undefined) {
+    return ''
+  }
+
+  if (base) {
+    return String(new URL(url, base))
+  }
+
+  return url
+}

lib/types.js

@@ -13,9 +13,27 @@
  * @typedef {Content | Root} Node
  * @typedef {Extract<Node, UnistParent>} Parent
  *
- * @typedef {(state: State, node: any, parent: Parent | undefined) => MdastNode | Array<MdastNode> | void} NodeHandle
+ * @callback Handle
+ *   Handle a particular element.
+ * @param {State} state
+ *   Info passed around about the current state.
+ * @param {Element} element
+ *   Element to transform.
+ * @param {Parent | undefined} parent
+ *   Parent of `element`.
+ * @returns {MdastNode | Array<MdastNode> | void}
+ *   mdast node or nodes.
  *
- * @typedef {(state: State, node: Element, parent: Parent | undefined) => MdastNode | Array<MdastNode> | void} Handle
+ * @callback NodeHandle
+ *   Handle a particular node.
+ * @param {State} state
+ *   Info passed around about the current state.
+ * @param {any} node
+ *   Node to transform.
+ * @param {Parent | undefined} parent
+ *   Parent of `node`.
+ * @returns {MdastNode | Array<MdastNode> | void}
+ *   mdast node or nodes.
  *
  * @typedef Options
  *   Configuration.
@@ -52,8 +70,12 @@
  *   *and* some non-phrasing nodes.
  * @property {Record<string, Handle | null | undefined> | null | undefined} [handlers]
  *   Object mapping tag names to functions handling the corresponding elements.
+ *
+ *   Merged into the defaults.
  * @property {Record<string, NodeHandle | null | undefined> | null | undefined} [nodeHandlers]
  *   Object mapping node types to functions handling the corresponding nodes.
+ *
+ *   Merged into the defaults.
  */
 
 export {}

package.json

@@ -42,6 +42,7 @@
     "@types/unist": "^2.0.0",
     "extend": "^3.0.0",
     "hast-util-phrasing": "^2.0.0",
+    "hast-util-to-html": "^8.0.4",
     "hast-util-to-text": "^3.0.0",
     "hast-util-whitespace": "^2.0.0",
     "mdast-util-phrasing": "^3.0.0",