Add improved docs

Closes GH-15.

Reviewed-by: Christian Murphy <christian.murphy.42@gmail.com>

index.js

@@ -1,73 +1,7 @@
 /**
- * @typedef {import('unist').Node} Node
- * @typedef {import('mdast').Root} MdastRoot
- * @typedef {import('mdast-util-to-nlcst').ParserInstance} ParserInstance
- * @typedef {import('mdast-util-to-nlcst').ParserConstructor} ParserConstructor
- * @typedef {import('mdast-util-to-nlcst').Options} Options
- * @typedef {import('unified').Processor<any, any, any, any>} Processor
- * @typedef {import('unified').Parser<any>} Parser
+ * @typedef {import('./lib/index.js').Options} Options
  */
 
-import {toNlcst} from 'mdast-util-to-nlcst'
-
-/**
- * Plugin to bridge or mutate to retext.
- *
- * If a destination processor is given, runs the destination with the new nlcst
- * tree (bridge-mode).
- * If a parser is given, returns the nlcst tree: further plugins run on that
- * tree (mutate-mode).
- *
- * @param destination
- *   Either a processor (`unified().use(retextEnglish)…`) or a parser.
- * @param options
- *   Configuration passed to `mdast-util-to-nlcst`.
- */
-const remarkRetext =
-  /**
-   * @type {(import('unified').Plugin<[Processor, Options?]|[Processor], MdastRoot, MdastRoot> & import('unified').Plugin<[Parser, Options?]|[Parser], MdastRoot, Node>)}
-   */
-  (
-    /**
-     * @param {Processor|Parser} destination
-     * @param {Options|undefined} options
-     */
-    function (destination, options) {
-      return destination && 'run' in destination
-        ? bridge(destination, options)
-        : mutate(destination, options)
-    }
-  )
+import remarkRetext from './lib/index.js'
 
 export default remarkRetext
-
-/**
- * Mutate-mode.
- * Further transformers run on the nlcst tree.
- *
- * @type {import('unified').Plugin<[Parser, Options?], MdastRoot, Node>}
- */
-function mutate(parser, options) {
-  // Assume the parser is a retext parser.
-  const Parser = /** @type {ParserInstance|ParserConstructor} */ (parser)
-  return (node, file) => toNlcst(node, file, Parser, options)
-}
-
-/**
- * Bridge-mode.
- * Runs the destination with the new nlcst tree.
- *
- * @type {import('unified').Plugin<[Processor, Options?], MdastRoot>}
- */
-function bridge(destination, options) {
-  return (node, file, next) => {
-    // Assume the parser is a retext parser.
-    const Parser = /** @type {ParserConstructor|ParserInstance} */ (
-      destination.freeze().Parser
-    )
-
-    destination.run(toNlcst(node, file, Parser, options), file, (error) => {
-      next(error)
-    })
-  }
-}

lib/index.js

@@ -0,0 +1,78 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('mdast').Root} MdastRoot
+ * @typedef {import('mdast-util-to-nlcst').ParserInstance} ParserInstance
+ * @typedef {import('mdast-util-to-nlcst').ParserConstructor} ParserConstructor
+ * @typedef {import('mdast-util-to-nlcst').Options} Options
+ * @typedef {import('unified').Processor<any, any, any, any>} Processor
+ * @typedef {import('unified').Parser<any>} Parser
+ */
+
+import {toNlcst} from 'mdast-util-to-nlcst'
+
+/**
+ * Plugin to support retext.
+ *
+ * *   If a destination processor is given, runs the plugins attached to it with
+ *     the new nlcst tree (bridge-mode).
+ *     This given processor must have a parser attached (this can be done by
+ *     using the plugin `retext-english` or similar) and should use other retext
+ *     plugins.
+ * *   If a parser is given, runs further plugins attached to the same processor
+ *     with the new tree (mutate-mode).
+ *     Such parsers are exported by packages like `retext-english` as `Parser`.
+ *     You should use other retext plugins after `remark-retext`.
+ *
+ * @param destination
+ *   Either a processor (`unified().use(retextEnglish)…`) or a parser.
+ * @param options
+ *   Configuration passed to `mdast-util-to-nlcst`.
+ */
+const remarkRetext =
+  /**
+   * @type {(import('unified').Plugin<[Processor, Options?]|[Processor], MdastRoot, MdastRoot> & import('unified').Plugin<[Parser, Options?]|[Parser], MdastRoot, Node>)}
+   */
+  (
+    /**
+     * @param {Processor|Parser} destination
+     * @param {Options|undefined} options
+     */
+    function (destination, options) {
+      return destination && 'run' in destination
+        ? bridge(destination, options)
+        : mutate(destination, options)
+    }
+  )
+
+export default remarkRetext
+
+/**
+ * Mutate-mode.
+ * Further transformers run on the nlcst tree.
+ *
+ * @type {import('unified').Plugin<[Parser, Options?], MdastRoot, Node>}
+ */
+function mutate(parser, options) {
+  // Assume the parser is a retext parser.
+  const Parser = /** @type {ParserInstance|ParserConstructor} */ (parser)
+  return (node, file) => toNlcst(node, file, Parser, options)
+}
+
+/**
+ * Bridge-mode.
+ * Runs the destination with the new nlcst tree.
+ *
+ * @type {import('unified').Plugin<[Processor, Options?], MdastRoot>}
+ */
+function bridge(destination, options) {
+  return (node, file, next) => {
+    // Assume the parser is a retext parser.
+    const Parser = /** @type {ParserConstructor|ParserInstance} */ (
+      destination.freeze().Parser
+    )
+
+    destination.run(toNlcst(node, file, Parser, options), file, (error) => {
+      next(error)
+    })
+  }
+}

package.json

@@ -1,7 +1,7 @@
 {
   "name": "remark-retext",
   "version": "5.0.0",
-  "description": "remark plugin to transform to retext",
+  "description": "remark plugin to support retext",
   "license": "MIT",
   "keywords": [
     "unified",
@@ -30,6 +30,7 @@
   "main": "index.js",
   "types": "index.d.ts",
   "files": [
+    "lib/",
     "index.d.ts",
     "index.js"
   ],
@@ -56,7 +57,7 @@
     "xo": "^0.45.0"
   },
   "scripts": {
-    "build": "rimraf \"*.d.ts\" && tsc && type-coverage",
+    "build": "rimraf \"lib/**/*.d.ts\" \"*.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node --conditions development test.js",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov npm run test-api",
@@ -85,8 +86,8 @@
     "ignoreCatch": true,
     "#": "needed `any`s",
     "ignoreFiles": [
-      "index.d.ts",
-      "index.js"
+      "lib/index.d.ts",
+      "lib/index.js"
     ]
   }
 }