Add docs to types

Author: wooorm

lib/index.js

@@ -23,8 +23,12 @@ export {all} from './all.js'
 const block = convert(['heading', 'paragraph', 'root'])
 
 /**
+ * Transform hast to mdast.
+ *
  * @param {Node} tree
+ *   Tree (hast).
  * @param {Options} [options]
+ *   Configuration (optional).
  */
 export function toMdast(tree, options = {}) {
   /** @type {Record<string, Element>} */

lib/types.js

@@ -25,12 +25,45 @@
  * @typedef {Record<string, unknown>} Properties
  *
  * @typedef Options
- * @property {Record<string, Handle>} [handlers]
- * @property {boolean} [document]
+ *   Configuration (optional).
  * @property {boolean} [newlines=false]
+ *   Keep line endings when collapsing whitespace.
+ *   The default collapses to a single space.
  * @property {string} [checked='[x]']
+ *   Value to use for a checked checkbox or radio input.
  * @property {string} [unchecked='[ ]']
+ *   Value to use for an unchecked checkbox or radio input.
  * @property {Array<string>} [quotes=['"']]
+ *   List of quotes to use.
+ *   Each value can be one or two characters.
+ *   When two, the first character determines the opening quote and the second
+ *   the closing quote at that level.
+ *   When one, both the opening and closing quote are that character.
+ *   The order in which the preferred quotes appear determines which quotes to
+ *   use at which level of nesting.
+ *   So, to prefer `‘’` at the first level of nesting, and `“”` at the second,
+ *   pass `['‘’', '“”']`.
+ *   If `<q>`s are nested deeper than the given amount of quotes, the markers
+ *   wrap around: a third level of nesting when using `['«»', '‹›']` should
+ *   have double guillemets, a fourth single, a fifth double again, etc.
+ * @property {boolean} [document]
+ *   Whether the given tree represents a complete document.
+ *   Applies when the `tree` is a `root` node.
+ *   When the tree represents a complete document, then things are wrapped in
+ *   paragraphs when needed, and otherwise they’re left as-is.
+ *   The default checks for whether there’s mixed content: some phrasing nodes
+ *   *and* some non-phrasing nodes.
+ * @property {Record<string, Handle>} [handlers]
+ *   Object mapping tag names or node types to functions handling the
+ *   corresponding nodes.
+ *   See `handlers/` for examples.
+ *
+ *   In a handler, you have access to `h`, which should be used to create mdast
+ *   nodes from hast nodes.
+ *   On `h`, there are several fields that may be of interest.
+ *   Most interesting of them is `h.wrapText`, which is `true` if the mdast
+ *   content can include newlines, and `false` if not (such as in headings or
+ *   table cells).
  *
  * @typedef Context
  * @property {Record<string, Element>} nodeById