docs: api

Signed-off-by: Lexus Drumgold <unicornware@flexdevelopment.llc>

.vscode/settings.json

@@ -239,7 +239,7 @@
   "todo-tree.tree.buttons.viewStyle": true,
   "todo-tree.tree.expanded": true,
   "todo-tree.tree.filterCaseSensitive": true,
-  "todo-tree.tree.scanMode": "workspace",
+  "todo-tree.tree.scanMode": "workspace only",
   "todo-tree.tree.showBadges": true,
   "todo-tree.tree.showCountsInTree": true,
   "todo-tree.tree.showCurrentScanMode": true,

README.md

@@ -19,6 +19,7 @@
 - [Install](#install)
 - [Use](#use)
 - [API](#api)
+  - [`unified().use(docastParse)`](#unifiedusedocastparse)
 - [Syntax](#syntax)
   - [Docblock](#docblock)
   - [Markdown](#markdown)
@@ -78,7 +79,19 @@ In browsers with [`esm.sh`][esmsh]:
 
 ## API
 
-**TODO**: api
+This package exports no identifiers. The default export is [`docastParse`](#unifiedusedocastparse).
+
+### `unified().use(docastParse)`
+
+Add support for docblock parsing.
+
+#### Parameters
+
+There are no parameters.
+
+#### Returns
+
+Nothing (`undefined`).
 
 ## Syntax
 
@@ -94,7 +107,7 @@ in extending markdown, more information is available in the [`mdast-util-from-ma
 
 ## Syntax tree
 
-The syntax tree format is [docast][docast].
+The syntax tree is [docast][docast].
 
 ## Types
 

src/__tests__/plugin.integration.spec.ts

@@ -3,8 +3,7 @@
  * @module docast-parse/tests/integration/plugin
  */
 
-import type { Options } from '@flex-development/docast-util-from-docs'
-import { constant, type Nilable } from '@flex-development/tutils'
+import { constant } from '@flex-development/tutils'
 import remarkDirective from 'remark-directive'
 import { read } from 'to-vfile'
 import { unified } from 'unified'
@@ -21,10 +20,10 @@ describe('integration:plugin', () => {
     })
   })
 
-  describe.each<['empty' | 'non-empty', Nilable<Options>?]>([
-    ['empty'],
-    ['non-empty', { transforms: [vi.fn()] }]
-  ])('%s document', (type, options) => {
+  describe.each<'empty' | 'non-empty'>([
+    'empty',
+    'non-empty'
+  ])('%s document', type => {
     let file: VFile
     let value: string
 
@@ -36,7 +35,7 @@ describe('integration:plugin', () => {
     it('should configure parser', () => {
       // Act
       const result = unified()
-        .use(testSubject, options)
+        .use(testSubject)
         .use(remarkDirective)
         .parse(file)
 

src/__tests__/plugin.spec-d.ts

@@ -4,27 +4,13 @@
  */
 
 import type { Root } from '@flex-development/docast'
-import type { Options } from '@flex-development/docast-util-from-docs'
-import type { Nilable } from '@flex-development/tutils'
+import type { EmptyArray } from '@flex-development/tutils'
 import type * as unified from 'unified'
 import type TestSubject from '../plugin'
 
 describe('unit-d:plugin', () => {
-  it('should match unified.Plugin<[Nilable<Options>?], string, Root>', () => {
+  it('should equal unified.Plugin<EmptyArray, string, Root>', () => {
     expectTypeOf<typeof TestSubject>()
-      .toMatchTypeOf<unified.Plugin<[Nilable<Options>?], string, Root>>()
-  })
-
-  describe('parameters', () => {
-    it('should be callable with [Nilable<Options>?]', () => {
-      expectTypeOf<typeof TestSubject>()
-        .parameters.toEqualTypeOf<[Nilable<Options>?]>()
-    })
-  })
-
-  describe('returns', () => {
-    it('should return void', () => {
-      expectTypeOf<typeof TestSubject>().returns.toBeVoid()
-    })
+      .toEqualTypeOf<unified.Plugin<EmptyArray, string, Root>>()
   })
 })

src/plugin.ts

@@ -5,10 +5,10 @@
 
 import type { Root } from '@flex-development/docast'
 import { fromDocs, type Options } from '@flex-development/docast-util-from-docs'
-import type { Nilable, Optional } from '@flex-development/tutils'
+import type { EmptyArray, Optional } from '@flex-development/tutils'
 import type { Extension as MdastExtension } from 'mdast-util-from-markdown'
 import type { Extension as MicromarkExtension } from 'micromark-util-types'
-import type { Data, Plugin, Processor } from 'unified'
+import type { Plugin, Processor } from 'unified'
 import type { VFile } from 'vfile'
 
 declare module 'unified' {
@@ -31,7 +31,8 @@ declare module 'unified' {
     micromarkExtensions?: Optional<MicromarkExtension[]>
   }
 
-  interface Settings extends Options {}
+  interface Settings
+    extends Omit<Options, 'mdastExtensions' | 'micromarkExtensions'> {}
 }
 
 /**
@@ -42,30 +43,9 @@ declare module 'unified' {
  *
  * @this {Processor}
  *
- * @param {Nilable<Options>?} [options] - Configuration options
  * @return {void} Nothing
  */
-function plugin(this: Processor, options?: Nilable<Options>): void {
-  /**
-   * Processor data.
-   *
-   * @const {Data} data
-   */
-  const data: Data = this.data()
-
-  // initialize extensions
-  data.fromMarkdownExtensions ??= []
-  data.micromarkExtensions ??= []
-
-  // initialize options
-  options ??= {}
-  options.mdastExtensions ??= []
-  options.micromarkExtensions ??= []
-
-  // configure extensions
-  data.fromMarkdownExtensions.push(...options.mdastExtensions)
-  data.micromarkExtensions.push(...options.micromarkExtensions)
-
+function plugin(this: Processor): void {
   /**
    * Docblock parser.
    *
@@ -75,10 +55,11 @@ function plugin(this: Processor, options?: Nilable<Options>): void {
    */
   const parser = (document: string, file: VFile): Root => {
     return fromDocs(String(file), {
+      // options are not documented in the readme.
+      // options should be set by plugins on `data` instead of passed by users.
       ...this.data('settings'),
-      ...options,
-      mdastExtensions: data.fromMarkdownExtensions,
-      micromarkExtensions: data.micromarkExtensions
+      mdastExtensions: this.data('fromMarkdownExtensions'),
+      micromarkExtensions: this.data('micromarkExtensions')
     })
   }
 
@@ -88,15 +69,13 @@ function plugin(this: Processor, options?: Nilable<Options>): void {
 /**
  * Add support for docblock parsing.
  *
- * @see {@linkcode Options}
  * @see {@linkcode Plugin}
  * @see {@linkcode Root}
  *
  * @this {Processor}
  *
- * @param {Nilable<Options>?} [options] - Configuration options
  * @return {void} Nothing
  */
-const docastParse: Plugin<[Nilable<Options>?], string, Root> = plugin
+const docastParse: Plugin<EmptyArray, string, Root> = plugin
 
 export default docastParse