Add improved docs

Author: wooorm

lib/index.js

@@ -39,14 +39,19 @@ import {commentMarker} from 'mdast-comment-marker'
 import {visit} from 'unist-util-visit'
 
 /**
+ * Search `tree` for a start and end comments matching `name` and change their
+ * “section” with `handler`.
+ *
  * @param {Node} node
  *   Tree to search.
  * @param {string} name
  *   Comment name to look for.
- * @param {Handler} callback
- *   Callback called when a range is found.
+ * @param {Handler} handler
+ *   Handle a section.
+ * @returns {void}
+ *   Nothing.
  */
-export function zone(node, name, callback) {
+export function zone(node, name, handler) {
   /** @type {number | undefined} */
   let level
   /** @type {Node | undefined} */
@@ -78,7 +83,7 @@ export function zone(node, name, callback) {
           // @ts-expect-error: Assume `scope` is a valid parent of `node`.
           const start = scope.children.indexOf(marker)
 
-          const nodes = callback(
+          const nodes = handler(
             marker,
             scope.children.slice(start + 1, index),
             node,

readme.md

@@ -18,6 +18,8 @@
 *   [Use](#use)
 *   [API](#api)
     *   [`zone(tree, name, handler)`](#zonetree-name-handler)
+    *   [`Handler`](#handler)
+    *   [`ZoneInfo`](#zoneinfo)
 *   [Types](#types)
 *   [Compatibility](#compatibility)
 *   [Security](#security)
@@ -45,7 +47,7 @@ the same but uses a heading to mark the start and end of sections.
 ## Install
 
 This package is [ESM only][esm].
-In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
+In Node.js (version 14.14+ and 16.0+), install with [npm][]:
 
 ```sh
 npm install mdast-zone
@@ -114,57 +116,74 @@ Bar.
 
 ## API
 
-This package exports the identifier `zone`.
+This package exports the identifier [`zone`][api-zone].
 There is no default export.
 
 ### `zone(tree, name, handler)`
 
-Search `tree` ([`Node`][node]) for comments marked `name` (`string`) and
-transform a section with `handler` ([`Function`][handler]).
+Search `tree` for a start and end comments matching `name` and change their
+“section” with `handler`.
 
-#### `function handler(start, nodes, end, info)`
+###### Parameters
 
-Callback called when a range is found.
+*   `tree` ([`Node`][node])
+    — tree to change
+*   `name` (`string`)
+    — comment name to look for
+*   `handler` ([`Handler`][api-handler])
+    — handle a section
 
-##### Parameters
+###### Returns
 
-Arguments.
+Nothing (`void`).
 
-###### `start`
+### `Handler`
 
-Start of range ([`Node`][node]), an [HTML][] (or MDX) comment node.
+Callback called when a section is found (TypeScript type).
 
-###### `nodes`
+###### Parameters
 
-Nodes between `start` and `end` ([`Array<Node>`][node]).
+*   `start` ([`Node`][node])
+    — start of section
+*   `nodes` ([`Array<Node>`][node])
+    — nodes between `start` and `end`
+*   `end` ([`Node`][node])
+    — end of section
+*   `info` ([`ZoneInfo`][api-zoneinfo])
+    — extra info
 
-###### `end`
+###### Returns
 
-End of range ([`Node`][node]), an [HTML][] (or MDX) comment node.
+Results (`Array<Node | null | undefined>`, optional).
 
-###### `info`
+If nothing is returned, nothing will be changed.
+If an array of nodes (can include `null` and `undefined`) is returned, the
+original section will be replaced by those nodes.
 
-Extra info (`Object`):
+### `ZoneInfo`
 
-*   `parent` ([`Node`][node]) — parent of the range
-*   `start` (`number`) — index of `start` in `parent`
-*   `end` (`number`) — index of `end` in `parent`
+Extra info (TypeScript type).
 
-###### Returns
+###### Fields
 
-Optional list of nodes to replace `start`, `nodes`, and `end` with
-([`Array<Node>?`][node]).
+*   `parent` ([`Node`][node])
+    — parent of the section
+*   `start` (`number`)
+    — index of `start` in `parent`
+*   `end` (`number` or `null`)
+    — index of `end` in `parent`
 
 ## Types
 
 This package is fully typed with [TypeScript][].
-This package exports the types `Handler` and `ZoneInfo`.
+It exports the additional types [`Handler`][api-handler] and
+[`ZoneInfo`][api-zoneinfo].
 
 ## Compatibility
 
 Projects maintained by the unified collective are compatible with all maintained
 versions of Node.js.
-As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
+As of now, that is Node.js 14.14+ and 16.0+.
 Our projects sometimes work with older versions, but this is not guaranteed.
 
 ## Security
@@ -266,12 +285,14 @@ abide by its terms.
 
 [node]: https://github.com/syntax-tree/mdast#nodes
 
-[html]: https://github.com/syntax-tree/mdast#html
-
 [mdast-util-heading-range]: https://github.com/syntax-tree/mdast-util-heading-range
 
 [hast]: https://github.com/syntax-tree/hast
 
 [hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize
 
-[handler]: #function-handlerstart-nodes-end-info
+[api-zone]: #zonetree-name-handler
+
+[api-handler]: #handler
+
+[api-zoneinfo]: #zoneinfo