如何让JSDoc解析React应用中的函数式组件？

解决JSXFragment识别报错 #

JSDoc 4.0.2默认解析器不支持JSXFragment语法，导致节点被忽略。可通过添加React专用插件解决：

• 安装插件：npm install jsdoc-react-plugin --save-dev
• 修改jsdoc.json的plugins数组，加入该插件：

"plugins": [
  "plugins/markdown",
  "jsdoc-react-plugin"
]

• 调整jsx配置项为React默认的pragma：

"jsx": {
  "pragma": "React.createElement"
}

如果使用React 17+的自动JSX转换，可直接移除jsx配置块。

解析函数式组件内部函数与Hooks #

JSDoc默认不会主动解析函数内部的嵌套内容，需通过显式标签配合插件实现：

• 给函数式组件添加@component标签，明确标记为React组件：

/**
 * 用户信息展示组件
 * @component
 */
export function UserInfo() {
  // ...
}

• 对内部函数、自定义Hooks添加@inner标签，让JSDoc识别为组件的内部成员：

/**
 * 格式化用户昵称
 * @inner
 * @param {string} nickname - 原始昵称
 * @returns {string} 格式化后的昵称
 */
const formatNickname = (nickname) => {
  return `@${nickname}`;
};

/**
 * 获取用户在线状态的自定义Hook
 * @inner
 * @returns {boolean} 在线状态
 */
const useUserOnlineStatus = () => {
  const [isOnline] = useContext(UserContext);
  return isOnline;
};

备选方案：用Babel解析增强兼容性 #

如果上述插件效果不佳，可借助Babel让JSDoc支持完整的React语法：

• 安装依赖：npm install babel-jsdoc-plugin @babel/core @babel/preset-react --save-dev
• 项目根目录创建.babelrc配置文件：

{
  "presets": ["@babel/preset-react"]
}

• 修改jsdoc.json的plugins数组：

"plugins": [
  "plugins/markdown",
  "babel-jsdoc-plugin"
]

通过Babel解析后，JSDoc能识别所有JSX语法，同时更准确地解析组件内部的函数与Hooks。

内容的提问来源于stack exchange，提问作者user6329530