Add improved docs

dev/lib/html.js

@@ -8,31 +8,28 @@
 import {matters} from '../matters.js'
 
 /**
- * Add support for turning frontmatter in markdown to HTML.
+ * Create an extension for `micromark` to support frontmatter when serializing
+ * to HTML.
  *
- * Function that can be called to get an HTML extension for micromark (passed
- * in `htmlExtensions`).
+ * > 👉 **Note**: this makes sure nothing is generated in the output HTML for
+ * > frontmatter.
  *
- * This makes sure nothing is generated for frontmatter.
- *
- * Supports YAML by default.
- * Can be configured to support other things.
- *
- * @param {Options} [options='yaml']
- *   Configuration (optional).
+ * @param {Options | null | undefined} [options='yaml']
+ *   Configuration.
  * @returns {HtmlExtension}
- *   HTML extension for micromark (passed in `htmlExtensions`).
+ *   Extension for `micromark` that can be passed in `htmlExtensions`, to
+ *   support frontmatter when serializing to HTML.
  */
 export function frontmatterHtml(options) {
-  const settings = matters(options)
+  const listOfMatters = matters(options)
   /** @type {HtmlExtension['enter']} */
   const enter = {}
   /** @type {HtmlExtension['exit']} */
   const exit = {}
   let index = -1
 
-  while (++index < settings.length) {
-    const type = settings[index].type
+  while (++index < listOfMatters.length) {
+    const type = listOfMatters[index].type
     enter[type] = start
     exit[type] = end
   }

dev/lib/syntax.js

@@ -17,18 +17,13 @@ import {types} from 'micromark-util-symbol/types.js'
 import {matters} from '../matters.js'
 
 /**
- * `micromark` extension to add support for parsing frontmatter in markdown.
- *
- * Function that can be called to get a syntax extension for micromark (passed
- * in `extensions`).
- *
- * Supports YAML by default.
- * Can be configured to support TOML and more.
+ * Create an extension for `micromark` to enable frontmatter syntax.
  *
  * @param {Options | null | undefined} [options='yaml']
- *   Configuration (optional).
+ *   Configuration.
  * @returns {Extension}
- *   Syntax extension for micromark (passed in `extensions`).
+ *   Extension for `micromark` that can be passed in `extensions`, to
+ *   enable frontmatter syntax.
  */
 export function frontmatter(options) {
   const listOfMatters = matters(options)

dev/matters.js

@@ -12,12 +12,11 @@
  *   Closing.
  *
  * @typedef MatterProps
- *   Fields of matter.
+ *   Fields describing a kind of matter.
  * @property {string} type
  *   Node type to tokenize as.
- * @property {boolean} [anywhere=false]
- *   Whether matter can be found anywhere in the document (`boolean`, default:
- *   `false`).
+ * @property {boolean | null | undefined} [anywhere=false]
+ *   Whether matter can be found anywhere in the document.
  *   Normally, only matter at the start of the document is recognized.
  *
  *   > 👉 **Note**: using this is a terrible idea.
@@ -27,30 +26,36 @@
  * @typedef MarkerProps
  *   Marker configuration.
  * @property {Info | string} marker
- *   Character used to construct fences.
+ *   Character repeated 3 times, used as complete fences.
  *
- *   The marker will be repeated.
  *   For example the character `'-'` will result in `'---'` being used as the
  *   fence
- *   Pass an `Info` interface to specify different characters for opening and
+ *   Pass `open` and `close` to specify different characters for opening and
  *   closing fences.
  * @property {never} [fence]
  *   If `marker` is set, `fence` must not be set.
  *
  * @typedef FenceProps
  *   Fence configuration.
  * @property {Info | string} fence
- *   String used as the complete fence.
+ *   Complete fences.
  *
  *   This can be used when fences contain different characters or lengths
  *   other than 3.
- *   Pass an `Info` interface to specify different characters for opening and
+ *   Pass `open` and `close` to interface to specify different characters for opening and
  *   closing fences.
  * @property {never} [marker]
  *   If `fence` is set, `marker` must not be set.
  *
  * @typedef {(MatterProps & FenceProps) | (MatterProps & MarkerProps)} Matter
- *   Matter object describing frontmatter.
+ *   Fields describing a kind of matter.
+ *
+ *   > 👉 **Note**: using `anywhere` is a terrible idea.
+ *   > It’s called frontmatter, not matter-in-the-middle or so.
+ *   > This makes your markdown less portable.
+ *
+ *   > 👉 **Note**: `marker` and `fence` are mutually exclusive.
+ *   > If `marker` is set, `fence` must not be set, and vice versa.
  *
  * @typedef {Matter | Preset | Array<Matter | Preset>} Options
  *   Configuration.