Add improved docs

Author: wooorm

lib/index.js

@@ -24,7 +24,7 @@
 import {truncate} from 'hast-util-truncate'
 
 /**
- * Truncate the tree to a certain comment.
+ * Truncate `tree` to a certain comment.
  *
  * @template {Node} Tree
  *   Type of tree.

readme.md

@@ -17,7 +17,9 @@
 *   [Install](#install)
 *   [Use](#use)
 *   [API](#api)
-    *   [`excerpt(tree, options?)`](#excerpttree-options)
+    *   [`excerpt(tree[, options])`](#excerpttree-options)
+    *   [`Options`](#options)
+*   [Syntax tree](#syntax-tree)
 *   [Types](#types)
 *   [Compatibility](#compatibility)
 *   [Security](#security)
@@ -47,7 +49,7 @@ a document, for use with [`rehype-meta`][rehype-meta].
 ## 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+ or 16.0+), install with [npm][]:
 
 ```sh
 npm install hast-util-excerpt
@@ -113,48 +115,62 @@ console.log(excerpt(tree));
 
 ## API
 
-This package exports the identifier `excerpt`.
+This package exports the identifier [`excerpt`][excerpt].
 There is no default export.
 
-### `excerpt(tree, options?)`
+### `excerpt(tree[, options])`
 
-Truncate the tree to a comment.
+Truncate `tree` to a certain comment.
 
-##### `options`
+###### Parameters
 
-Configuration (optional).
+*   `tree` ([`Node`][node])
+    — tree to truncate
+*   `options` ([`Options`][options])
+    — configuration (optional)
 
-###### `options.comment`
+###### Returns
+
+Truncated copy of `tree` ([`Node`][node]) when a comment is found, `undefined`
+otherwise.
+
+### `Options`
+
+Configuration (TypeScript type).
+
+##### Fields
+
+###### `comment`
 
 Comment value to search for (`string`, default: `'more'`).
 
-###### `options.maxSearchSize`
+###### `maxSearchSize`
 
 How far to search for the comment before bailing (`number`, default: `2048`).
 The goal of this project is to find user-defined explicit excerpts, that are
 assumed to be somewhat reasonably placed.
 This option prevents searching giant documents for some comment that probably
 won’t be found at the end.
 
-###### `options.ignore`
+###### `ignore`
 
-Nodes to exclude from the resulting tree (`Array<Node>`).
+Nodes to exclude from the resulting tree ([`Array<Node>`][node]).
 These are not counted towards `size`.
 
-###### Returns
+## Syntax tree
 
-Truncated copy of `tree` if there’s a comment, `undefined` otherwise (`Node?`).
+The syntax tree is [hast][].
 
 ## Types
 
 This package is fully typed with [TypeScript][].
-It exports the additional type `Options`.
+It exports the additional type [`Options`][options].
 
 ## 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
@@ -243,3 +259,9 @@ abide by its terms.
 [rehype-infer-description-meta]: https://github.com/rehypejs/rehype-infer-description-meta
 
 [rehype-meta]: https://github.com/rehypejs/rehype-meta
+
+[excerpt]: #excerpttree-options
+
+[options]: #options
+
+[node]: https://github.com/syntax-tree/hast#nodes