babel-plugin-fix-jsdoc

yarn add -D babel-plugin-fix-jsdoc
npm install --save-dev babel-plugin-fix-jsdoc

Babel's parser attaches comments as leading and trailing to nodes. This means that when a new node is injected by a transform, there's a risk that a JSDoc block comment that was meant to be leading, will be printed as trailing to the node after which the injection happened, seprating documentation from declaration. This can lead to serious bugs, for example:

import { useMemo } from 'preact/hooks';

/**
 * A component exported as default feature.
 * @param {object} params
 * @param {string} params.suffix
 */
import { jsxs as _jsxs } from "react/jsx-runtime"; // ⬅ BREAKS JSDOC!!!
export default function Component({
  suffix
}) {
  return /*#__PURE__*/_jsxs("div", {
    children: ["example", suffix ? /*#__PURE__*/_jsxs("span", {
      children: ["-", suffix]
    }) : null]
  });
}

This very simply transform iterates through comments of each node in the program, and makes sure that block comments are always recorded as leading.

Installation

Always include this as the first plugin in the list of plugins:

{
 "plugins": [
  "fix-jsdoc",
  [
   "@babel/plugin-transform-react-jsx",
   {
    "runtime": "automatic"
   }
  ]
 ]
}