From 7ca8974f1418ee6f512dcc0ef9ddc3e2bbca453b Mon Sep 17 00:00:00 2001
From: Titus Wormer <tituswormer@gmail.com>
Date: Wed, 22 Jan 2025 16:05:40 +0100
Subject: [PATCH] Refactor to use `@import`s

---
 lib/index.js | 13 ++++++-------
 readme.md    | 44 +++++++++++++++++++++++++-------------------
 2 files changed, 31 insertions(+), 26 deletions(-)

diff --git a/lib/index.js b/lib/index.js
index 42a6e81..9a8b9c4 100644
--- a/lib/index.js
+++ b/lib/index.js
@@ -1,10 +1,9 @@
-/// <reference types="remark-parse" />
-/// <reference types="remark-stringify" />
-/// <reference types="mdast-util-directive" />
-
 /**
- * @typedef {import('mdast').Root} Root
- * @typedef {import('unified').Processor<Root>} Processor
+ * @import {} from 'mdast-util-directive'
+ * @import {Root} from 'mdast'
+ * @import {} from 'remark-arse'
+ * @import {} from 'remark-stringify'
+ * @import {Processor} from 'unified'
  */
 
 import {directiveFromMarkdown, directiveToMarkdown} from 'mdast-util-directive'
@@ -23,7 +22,7 @@ import {directive} from 'micromark-extension-directive'
 export default function remarkDirective() {
   // @ts-expect-error: TS is wrong about `this`.
   // eslint-disable-next-line unicorn/no-this-assignment
-  const self = /** @type {Processor} */ (this)
+  const self = /** @type {Processor<Root>} */ (this)
   const data = self.data()
 
   const micromarkExtensions =
diff --git a/readme.md b/readme.md
index 4bac7ed..f7ec39d 100644
--- a/readme.md
+++ b/readme.md
@@ -104,10 +104,11 @@ A :i[lovely] language know as :abbr[HTML]{title="HyperText Markup Language"}.
 …and our module `example.js` contains:
 
 ```js
-// Register `hName`, `hProperties` types, used when turning markdown to HTML:
-/// <reference types="mdast-util-to-hast" />
-// Register directive nodes in mdast:
-/// <reference types="mdast-util-directive" />
+/**
+ * @import {} from 'mdast-util-directive'
+ * @import {} from 'mdast-util-to-hast'
+ * @import {Root} from 'mdast'
+ */
 
 import {h} from 'hastscript'
 import rehypeFormat from 'rehype-format'
@@ -135,7 +136,7 @@ console.log(String(file))
 // See below for others examples.
 function myRemarkPlugin() {
   /**
-   * @param {import('mdast').Root} tree
+   * @param {Root} tree
    *   Tree.
    * @returns {undefined}
    *   Nothing.
@@ -199,19 +200,21 @@ It’s based on the example in Use above.
 If `myRemarkPlugin` was replaced with this function:
 
 ```js
-// Register `hName`, `hProperties` types, used when turning markdown to HTML:
-/// <reference types="mdast-util-to-hast" />
-// Register directive nodes in mdast:
-/// <reference types="mdast-util-directive" />
+/**
+ * @import {} from 'mdast-util-directive'
+ * @import {} from 'mdast-util-to-hast'
+ * @import {Root} from 'mdast'
+ * @import {VFile} from 'vfile'
+ */
 
 import {visit} from 'unist-util-visit'
 
 // This plugin is an example to turn `::youtube` into iframes.
 function myRemarkPlugin() {
   /**
-   * @param {import('mdast').Root} tree
+   * @param {Root} tree
    *   Tree.
-   * @param {import('vfile').VFile} file
+   * @param {VFile} file
    *   File.
    * @returns {undefined}
    *   Nothing.
@@ -279,10 +282,11 @@ It’s based on the example in Use above.
 If `myRemarkPlugin` was replaced with this function:
 
 ```js
-// Register `hName`, `hProperties` types, used when turning markdown to HTML:
-/// <reference types="mdast-util-to-hast" />
-// Register directive nodes in mdast:
-/// <reference types="mdast-util-directive" />
+/**
+ * @import {} from 'mdast-util-directive'
+ * @import {} from 'mdast-util-to-hast'
+ * @import {Root} from 'mdast'
+ */
 
 import {h} from 'hastscript'
 import {visit} from 'unist-util-visit'
@@ -291,7 +295,7 @@ import {visit} from 'unist-util-visit'
 // attributes.
 function myRemarkPlugin() {
   /**
-   * @param {import('mdast').Root} tree
+   * @param {Root} tree
    *   Tree.
    * @returns {undefined}
    *   Nothing.
@@ -372,14 +376,16 @@ If you’re working with the syntax tree, you can register the new node types
 with `@types/mdast` by adding a reference:
 
 ```js
-// Register directive nodes in mdast:
-/// <reference types="mdast-util-directive" />
+/**
+ * @import {} from 'mdast-util-directive'
+ * @import {Root} from 'mdast'
+ */
 
 import {visit} from 'unist-util-visit'
 
 function myRemarkPlugin() {
   /**
-   * @param {import('mdast').Root} tree
+   * @param {Root} tree
    *   Tree.
    * @returns {undefined}
    *   Nothing.