docs: api

Signed-off-by: Lexus Drumgold <[email protected]>

Author: unicornware

README.md

@@ -19,6 +19,9 @@
 - [Install](#install)
 - [Use](#use)
 - [API](#api)
+  - [`fromDocs(value[, options])`](#fromdocsvalue-options)
+  - [`Options`](#options)
+  - [`Transform`](#transform)
 - [Syntax](#syntax)
   - [Docblock](#docblock)
   - [Markdown](#markdown)
@@ -306,7 +309,47 @@ root[9]
 
 ## API
 
-**TODO**: api
+This package exports the identifier [`fromDocs`](#fromdocsvalue-options). There is no default export.
+
+### `fromDocs(value[, options])`
+
+Turn docblocks into a syntax tree.
+
+#### Parameters
+
+- `value` ([`VFile`][vfile] | `string`) — source document or file containing docblocks to parse
+- `options` ([`Options`](#options), optional) — configuration options
+
+#### Returns
+
+docast tree ([`Root`][docast-tree])
+
+### `Options`
+
+Configuration options (TypeScript type).
+
+#### Properties
+
+- `codeblocks` (`OneOrMany<RegExp | string>`, optional) &mdash; block tag node names and tags, or regular
+  expressions, matching block tags that should have their text converted to [`Code`][mdast-code] when parsed as markdown
+  - **default**: `'example'`
+- `mdastExtensions` ([`MdastExtension[]`][mdast-util-extension], optional) &mdash; markdown extensions to change how
+  micromark tokens are converted to nodes
+- `micromarkExtensions` ([`MicromarkExtension[]`][micromark-extension], optional) &mdash; micromark extensions to change
+  how markdown is parsed
+- `transforms` ([`Transform[]`](#transform), optional) &mdash; tree transforms
+
+### `Transform`
+
+Change the AST after parsing is complete (TypeScript type).
+
+#### Parameters
+
+- `tree` ([`Root`][docast-tree]) &mdash; tree to transform
+
+#### Returns
+
+Nothing
 
 ## Syntax
 
@@ -333,10 +376,15 @@ This package is fully typed with [TypeScript][typescript].
 See [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
 [docast-parse]: https://github.com/flex-development/docast-parse
+[docast-tree]: https://github.com/flex-development/docast#root
 [docast]: https://github.com/flex-development/docast
 [docblock]: https://github.com/flex-development/docast#docblock-comment
 [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+[mdast-code]: https://github.com/syntax-tree/mdast#code
+[mdast-util-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension
 [mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
+[micromark-extension]: https://github.com/micromark/micromark#extensions
 [micromark]: https://github.com/micromark/micromark
 [typescript]: https://www.typescriptlang.org
 [unified]: https://github.com/unifiedjs/unified
+[vfile]: https://github.com/vfile/vfile#api

src/interfaces/__tests__/options.spec-d.ts

@@ -5,8 +5,8 @@
 
 import type { Transform } from '#src/types'
 import type { Nilable, OneOrMany } from '@flex-development/tutils'
-import type * as mdast from 'mdast-util-from-markdown'
-import type * as micromark from 'micromark-util-types'
+import type { Extension as MdastExtension } from 'mdast-util-from-markdown'
+import type { Extension as MicromarkExtension } from 'micromark-util-types'
 import type TestSubject from '../options'
 
 describe('unit-d:interfaces/Options', () => {
@@ -16,16 +16,16 @@ describe('unit-d:interfaces/Options', () => {
       .toEqualTypeOf<Nilable<OneOrMany<RegExp | string>>>()
   })
 
-  it('should match [mdastExtensions?: Nilable<mdast.Extension[]>]', () => {
+  it('should match [mdastExtensions?: Nilable<MdastExtension[]>]', () => {
     expectTypeOf<TestSubject>()
       .toHaveProperty('mdastExtensions')
-      .toEqualTypeOf<Nilable<mdast.Extension[]>>()
+      .toEqualTypeOf<Nilable<MdastExtension[]>>()
   })
 
-  it('should match [micromarkExtensions?: Nilable<micromark.Extension[]>]', () => {
+  it('should match [micromarkExtensions?: Nilable<MicromarkExtension[]>]', () => {
     expectTypeOf<TestSubject>()
       .toHaveProperty('micromarkExtensions')
-      .toEqualTypeOf<Nilable<micromark.Extension[]>>()
+      .toEqualTypeOf<Nilable<MicromarkExtension[]>>()
   })
 
   it('should match [transforms?: Nilable<Transform[]>]', () => {

src/interfaces/options.ts

@@ -6,11 +6,11 @@
 import type { Transform } from '#src/types'
 import type { Nilable, OneOrMany } from '@flex-development/tutils'
 import type { Code } from 'mdast'
-import type * as mdast from 'mdast-util-from-markdown'
-import type * as micromark from 'micromark-util-types'
+import type { Extension as MdastExtension } from 'mdast-util-from-markdown'
+import type { Extension as MicromarkExtension } from 'micromark-util-types'
 
 /**
- * Parser options.
+ * Configuration options.
  */
 interface Options {
   /**
@@ -23,20 +23,20 @@ interface Options {
   codeblocks?: Nilable<OneOrMany<RegExp | string>>
 
   /**
-   * Extensions to change how mdast tokens are converted to syntax tree nodes.
+   * Markdown extensions to change how micromark tokens are converted to nodes.
    *
-   * @see {@linkcode mdast.Extension}
-   * @see https://github.com/syntax-tree/mdast-util-from-markdown
+   * @see {@linkcode MdastExtension}
+   * @see https://github.com/syntax-tree/mdast-util-from-markdown#list-of-extensions
    */
-  mdastExtensions?: Nilable<mdast.Extension[]>
+  mdastExtensions?: Nilable<MdastExtension[]>
 
   /**
-   * Markdown syntax extensions.
+   * Micromark extensions to change how markdown is parsed.
    *
-   * @see {@linkcode micromark.Extension}
+   * @see {@linkcode MicromarkExtension}
    * @see https://github.com/micromark/micromark#extensions
    */
-  micromarkExtensions?: Nilable<micromark.Extension[]>
+  micromarkExtensions?: Nilable<MicromarkExtension[]>
 
   /**
    * Tree transforms.