From 0b9798c48c1b2d5cc8fa552750305b1ecf490c8d Mon Sep 17 00:00:00 2001
From: Titus Wormer <tituswormer@gmail.com>
Date: Thu, 30 Mar 2023 15:09:23 +0200
Subject: [PATCH] Add improved JSDoc

---
 dev/lib/html.js   | 44 ++++++++++++++++++++++++++++++++++----------
 dev/lib/syntax.js |  4 ++++
 readme.md         |  2 +-
 3 files changed, 39 insertions(+), 11 deletions(-)

diff --git a/dev/lib/html.js b/dev/lib/html.js
index 28036eb..330264f 100644
--- a/dev/lib/html.js
+++ b/dev/lib/html.js
@@ -6,22 +6,40 @@
 
 /**
  * @typedef {[string, string]} Attribute
- * @typedef {'containerDirective' | 'leafDirective' | 'textDirective'} DirectiveType
- *
- * @typedef Directive
- * @property {DirectiveType} type
- * @property {string} name
- * @property {string | undefined} [label]
- * @property {Record<string, string> | undefined} [attributes]
- * @property {string | undefined} [content]
- * @property {number | undefined} [_fenceCount]
+ *   Internal tuple representing an attribute.
+ */
+
+/**
+ * @typedef {Record<string, Handle>} HtmlOptions
+ *   Configuration.
  *
  * @callback Handle
+ *   Handle a directive.
  * @param {CompileContext} this
+ *   Current context.
  * @param {Directive} directive
+ *   Directive.
  * @returns {boolean | void}
+ *   Signal that the directive could not be handled, in which case the fallback
+ *   is used (when given: a special handle for `'*'`).
  *
- * @typedef {Record<string, Handle>} HtmlOptions
+ * @typedef Directive
+ *   Structure representing a directive
+ * @property {DirectiveType} type
+ *   Kind.
+ * @property {string} name
+ *   Name of directive.
+ * @property {string | undefined} [label]
+ *   Compiled HTML content that was in `[brackets]`.
+ * @property {Record<string, string> | undefined} [attributes]
+ *   Object w/ HTML attributes.
+ * @property {string | undefined} [content]
+ *   Compiled HTML content inside container directive.
+ * @property {number | undefined} [_fenceCount]
+ *   Private :)
+ *
+ * @typedef {'containerDirective' | 'leafDirective' | 'textDirective'} DirectiveType
+ *   Kind.
  */
 
 import {ok as assert} from 'uvu/assert'
@@ -30,8 +48,14 @@ import {parseEntities} from 'parse-entities'
 const own = {}.hasOwnProperty
 
 /**
+ * Create an extension for `micromark` to support directives when serializing
+ * to HTML.
+ *
  * @param {HtmlOptions | null | undefined} [options]
+ *   Configuration.
  * @returns {HtmlExtension}
+ *   Extension for `micromark` that can be passed in `htmlExtensions`, to
+ *   support directives when serializing to HTML.
  */
 export function directiveHtml(options) {
   const options_ = options || {}
diff --git a/dev/lib/syntax.js b/dev/lib/syntax.js
index e84b03f..8eb1eae 100644
--- a/dev/lib/syntax.js
+++ b/dev/lib/syntax.js
@@ -8,7 +8,11 @@ import {directiveLeaf} from './directive-leaf.js'
 import {directiveText} from './directive-text.js'
 
 /**
+ * Create an extension for `micromark` to enable directive syntax.
+ *
  * @returns {Extension}
+ *   Extension for `micromark` that can be passed in `extensions`, to
+ *   enable directive syntax.
  */
 export function directive() {
   return {
diff --git a/readme.md b/readme.md
index 9f11599..3d73526 100644
--- a/readme.md
+++ b/readme.md
@@ -116,7 +116,7 @@ be handled, in which case the fallback is used (when given).
 
 ### `Directive`
 
-An object representing a directive.
+Structure representing a directive.
 
 ###### Fields