docs: when should i use this?

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

Author: unicornware

.github/infrastructure.yml

@@ -171,7 +171,7 @@ repository:
   automated_security_fixes: true
   default_branch: main
   delete_branch_on_merge: true
-  description: unified compliant parser for docast
+  description: unified plugin to add support for parsing docblock comments
   has_issues: true
   has_projects: true
   has_wiki: false
@@ -186,23 +186,19 @@ repository:
   squash_merge_commit_message: BLANK
   squash_merge_commit_title: PR_TITLE
   topics:
-    - abstract-syntax-tree
     - ast
     - comment-parser
-    - doc
     - docast
     - docblock
+    - docs
     - documentation
     - jsdoc
     - markdown
     - mdast
     - syntax-tree
     - tsdoc
-    - typedoc
     - typescript
     - unified
-    - unist
-    - unist-spec
   visibility: public
   vulnerability_alerts: true
   web_commit_signoff_required: true

README.md

@@ -10,7 +10,7 @@
 [![vitest](https://img.shields.io/badge/-vitest-6e9f18?style=flat&logo=vitest&logoColor=ffffff)](https://vitest.dev/)
 [![yarn](https://img.shields.io/badge/-yarn-2c8ebb?style=flat&logo=yarn&logoColor=ffffff)](https://yarnpkg.com/)
 
-[**unified**][unified] compliant parser for [**docast**][docast].
+[**docast**][docast] x [**unified**][unified] plugin to add support for parsing docblock comments.
 
 ## Contents
 
@@ -26,12 +26,17 @@
 
 ## What is this?
 
-This package is a [unified][unified] plugin that defines how to take source code as input and turn it into a [docblock
-syntax tree][docast].
+This package is a [unified][unified] plugin that defines how to take [docblock][docblock] input and turn it into a
+syntax tree.
 
 ## When should I use this?
 
-**TODO**: when should i use this?
+This plugin adds support to unified for parsing [docblock comments][docblock]. If you don’t use plugins and want to
+access the syntax tree directly, you can use [`docast-util-from-docs`][docast-util-from-docs] instead.
+
+You can also combine this plugin with other unified plugins to add extensions for parsing markdown in docblock comments.
+Notable packages include [`remark-directive`][remark-directive], [`remark-gfm`][remark-gfm], and
+[`remark-math`][remark-math].
 
 ## Install
 
@@ -89,9 +94,14 @@ This package is fully typed with [TypeScript][typescript].
 
 See [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
+[docast-util-from-docs]: https://github.com/flex-development/docast-util-from-docs
 [docast]: https://github.com/flex-development/docast
+[docblock]: https://github.com/flex-development/docast#docblock-comment
 [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
 [esmsh]: https://esm.sh/
+[remark-directive]: https://github.com/remarkjs/remark-directive
+[remark-gfm]: https://github.com/remarkjs/remark-gfm
+[remark-math]: https://github.com/remarkjs/remark-math
 [typescript]: https://www.typescriptlang.org
 [unified]: https://github.com/unifiedjs/unified
 [yarn]: https://yarnpkg.com

package.json

@@ -1,25 +1,21 @@
 {
   "name": "@flex-development/docast-parse",
-  "description": "unified compliant parser for docast",
+  "description": "unified plugin to add support for parsing docblock comments",
   "version": "1.0.0-alpha.5",
   "keywords": [
-    "abstract-syntax-tree",
     "ast",
     "comment-parser",
-    "doc",
     "docast",
     "docblock",
+    "docs",
     "documentation",
     "jsdoc",
     "markdown",
     "mdast",
     "syntax-tree",
     "tsdoc",
-    "typedoc",
     "typescript",
-    "unified",
-    "unist",
-    "unist-spec"
+    "unified"
   ],
   "license": "BSD-3-Clause",
   "homepage": "https://github.com/flex-development/docast-parse",
@@ -139,9 +135,7 @@
     "is-ci": "3.0.1",
     "jsonc-eslint-parser": "2.4.0",
     "lint-staged": "15.2.1",
-    "mdast-util-directive": "3.0.0",
     "mdast-util-from-markdown": "2.0.0",
-    "micromark-extension-directive": "3.0.0",
     "micromark-util-types": "2.0.0",
     "node-notifier": "10.0.1",
     "prettier": "3.2.4",

src/__tests__/plugin.integration.spec.ts

@@ -5,8 +5,7 @@
 
 import type { Options } from '@flex-development/docast-util-from-docs'
 import { constant, type Nilable } from '@flex-development/tutils'
-import { directiveFromMarkdown } from 'mdast-util-directive'
-import { directive } from 'micromark-extension-directive'
+import remarkDirective from 'remark-directive'
 import { read } from 'to-vfile'
 import { unified } from 'unified'
 import { inspectNoColor } from 'unist-util-inspect'
@@ -24,10 +23,7 @@ describe('integration:plugin', () => {
 
   describe.each<['empty' | 'non-empty', Nilable<Options>?]>([
     ['empty'],
-    ['non-empty', {
-      mdastExtensions: [directiveFromMarkdown()],
-      micromarkExtensions: [directive()]
-    }]
+    ['non-empty', { transforms: [vi.fn()] }]
   ])('%s document', (type, options) => {
     let file: VFile
     let value: string
@@ -37,9 +33,12 @@ describe('integration:plugin', () => {
       file = type === 'empty' ? new VFile(value) : await read(value)
     })
 
-    it('should configure parser', async () => {
+    it('should configure parser', () => {
       // Act
-      const result = unified().use(testSubject, options).parse(file)
+      const result = unified()
+        .use(testSubject, options)
+        .use(remarkDirective)
+        .parse(file)
 
       // Expect
       expect(result).toMatchSnapshot()

yarn.lock

@@ -1457,9 +1457,7 @@ __metadata:
     is-ci: "npm:3.0.1"
     jsonc-eslint-parser: "npm:2.4.0"
     lint-staged: "npm:15.2.1"
-    mdast-util-directive: "npm:3.0.0"
     mdast-util-from-markdown: "npm:2.0.0"
-    micromark-extension-directive: "npm:3.0.0"
     micromark-util-types: "npm:2.0.0"
     node-notifier: "npm:10.0.1"
     prettier: "npm:3.2.4"
@@ -7060,7 +7058,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"mdast-util-directive@npm:3.0.0, mdast-util-directive@npm:^3.0.0":
+"mdast-util-directive@npm:^3.0.0":
   version: 3.0.0
   resolution: "mdast-util-directive@npm:3.0.0"
   dependencies:
@@ -7407,7 +7405,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"micromark-extension-directive@npm:3.0.0, micromark-extension-directive@npm:^3.0.0":
+"micromark-extension-directive@npm:^3.0.0":
   version: 3.0.0
   resolution: "micromark-extension-directive@npm:3.0.0"
   dependencies: