Add docs to types

lib/index.js

@@ -14,15 +14,57 @@
  * @typedef {import('estree-jsx').JSXIdentifier} JSXIdentifier
  *
  * @typedef Options
- * @property {'automatic'|'classic'} [runtime='classic']
+ *   Configuration (optional).
+ *
+ *   > 👉 **Note**: you can also configure `runtime`, `importSource`, `pragma`,
+ *   > and `pragmaFrag` from within files through comments.
+ * @property {'automatic' | 'classic'} [runtime='classic']
+ *   Choose the runtime.
+ *
+ *   Comment form: `@jsxRuntime theRuntime`.
  * @property {string} [importSource='react']
+ *   Place to import `jsx`, `jsxs`, `jsxDEV`, and/or `Fragment` from, when the
+ *   effective runtime is automatic.
+ *
+ *   Comment form: `@jsxImportSource theSource`.
+ *
+ *   > 👉 **Note**: `/jsx-runtime` or `/jsx-dev-runtime` is appended to this
+ *   > provided source.
+ *   > In CJS, that can resolve to a file, as in `theSource/jsx-runtime.js`,
+ *   > but for ESM an export map needs to be set up to point to files:
+ *   >
+ *   > ```js
+ *   > // …
+ *   > "exports": {
+ *   >   // …
+ *   >   "./jsx-runtime": "./path/to/jsx-runtime.js",
+ *   >   "./jsx-dev-runtime": "./path/to/jsx-runtime.js"
+ *   >   // …
+ *   > ```
  * @property {string} [pragma='React.createElement']
+ *   Identifier or member expression to call when the effective runtime is
+ *   classic.
+ *
+ *   Comment form: `@jsx identifier`.
  * @property {string} [pragmaFrag='React.Fragment']
+ *   Identifier or member expression to use as a symbol for fragments when the
+ *   effective runtime is classic.
+ *
+ *   Comment form: `@jsxFrag identifier`.
  * @property {boolean} [development=false]
+ *   Import `jsxDEV` from `theSource/jsx-dev-runtime.js` and add location info
+ *   on where a component originated from.
+ *
+ *   This helps debugging but adds a lot of code that you don’t want in
+ *   production.
+ *   Only used in the automatic runtime.
  * @property {string} [filePath]
+ *   File path to the original source file.
+ *   Used in the location info when using the automatic runtime with
+ *   `development: true`.
  *
  * @typedef Annotations
- * @property {'automatic'|'classic'} [jsxRuntime]
+ * @property {'automatic' | 'classic'} [jsxRuntime]
  * @property {string} [jsx]
  * @property {string} [jsxFrag]
  * @property {string} [jsxImportSource]
@@ -35,11 +77,17 @@ import {name as isIdentifierName} from 'estree-util-is-identifier-name'
 const regex = /@(jsx|jsxFrag|jsxImportSource|jsxRuntime)\s+(\S+)/g
 
 /**
- * @template {Node} T
- * @param {T} tree
+ * Turn JSX in `tree` into function calls: `<x />` -> `h('x')`!
+ *
+ * @template {Node} Tree
+ * @param {Tree} tree
+ *   Tree to transform.
  * @param {Options} [options={}]
- * @returns {T}
+ *   Configuration (optional).
+ * @returns {Tree}
+ *   Given, modified, tree.
  */
+// To do next major: do not return the given Node.
 export function buildJsx(tree, options = {}) {
   let automatic = options.runtime === 'automatic'
   /** @type {Annotations} */
@@ -194,15 +242,15 @@ export function buildJsx(tree, options = {}) {
         }
       }
 
-      /** @type {MemberExpression|Literal|Identifier} */
+      /** @type {MemberExpression | Literal | Identifier} */
       let name
       /** @type {Array<Property>} */
       let fields = []
       /** @type {Array<Expression>} */
       const objects = []
-      /** @type {Array<Expression|SpreadElement>} */
+      /** @type {Array<Expression | SpreadElement>} */
       let parameters = []
-      /** @type {Expression|undefined} */
+      /** @type {Expression | undefined} */
       let key
 
       // Do the stuff needed for elements.
@@ -215,7 +263,7 @@ export function buildJsx(tree, options = {}) {
           name = create(name, {type: 'Literal', value: name.name})
         }
 
-        /** @type {boolean|undefined} */
+        /** @type {boolean | undefined} */
         let spread
         const attributes = node.openingElement.attributes
         let index = -1
@@ -289,9 +337,9 @@ export function buildJsx(tree, options = {}) {
         objects.push({type: 'ObjectExpression', properties: fields})
       }
 
-      /** @type {Expression|undefined} */
+      /** @type {Expression | undefined} */
       let props
-      /** @type {MemberExpression|Literal|Identifier} */
+      /** @type {MemberExpression | Literal | Identifier} */
       let callee
 
       if (objects.length > 1) {
@@ -450,11 +498,11 @@ function toProperty(node) {
 }
 
 /**
- * @param {JSXMemberExpression|JSXNamespacedName|JSXIdentifier} node
- * @returns {MemberExpression|Identifier|Literal}
+ * @param {JSXMemberExpression | JSXNamespacedName | JSXIdentifier} node
+ * @returns {MemberExpression | Identifier | Literal}
  */
 function toIdentifier(node) {
-  /** @type {MemberExpression|Identifier|Literal} */
+  /** @type {MemberExpression | Identifier | Literal} */
   let replace
 
   if (node.type === 'JSXMemberExpression') {
@@ -486,16 +534,16 @@ function toIdentifier(node) {
 
 /**
  * @param {string} id
- * @returns {Identifier|Literal|MemberExpression}
+ * @returns {Identifier | Literal | MemberExpression}
  */
 function toMemberExpression(id) {
   const identifiers = id.split('.')
   let index = -1
-  /** @type {Identifier|Literal|MemberExpression|undefined} */
+  /** @type {Identifier | Literal | MemberExpression | undefined} */
   let result
 
   while (++index < identifiers.length) {
-    /** @type {Identifier|Literal} */
+    /** @type {Identifier | Literal} */
     const prop = isIdentifierName(identifiers[index])
       ? {type: 'Identifier', name: identifiers[index]}
       : {type: 'Literal', value: identifiers[index]}