为何Styleguidist无法识别React函数组件内部的JSDoc注释

React Styleguidist 底层依赖 react-docgen（JS项目）或 react-docgen-typescript（TS项目）解析组件注释，默认仅会扫描组件顶层的描述注释、组件props定义，组件内部未对外暴露的方法属于实现细节，默认不会被识别和展示。

• 1. 调整Styleguidist配置开启内部公共方法解析
     如果是TS项目，修改styleguide.config.js增加如下配置：

module.exports = {
  // 其余原有配置保持不变
  propsParser: require('react-docgen-typescript').parse,
  reactDocgenTypescriptOptions: {
    // 开启对@public标记的成员的提取
    shouldExtractMethodParams: true,
    extractComponentDescription: (component) => component.description,
  }
}

如果是JS项目，修改配置指定react-docgen的handlers包含方法处理器：

const { handlers } = require('react-docgen')
module.exports = {
  // 其余原有配置保持不变
  reactDocgen: {
    handlers: [...handlers.defaultHandlers, handlers.createMethodHandler()]
  }
}

• 2. 对外暴露需要展示的方法
     仅当方法属于组件对外提供的公共API时，才需要展示在文档中。你需要通过forwardRef + useImperativeHandle将方法挂载到组件实例上，才会被解析器识别为公共成员，示例如下：

import { useParams, useImperativeHandle, forwardRef, useState } from 'react'

// 定义组件对外暴露的方法类型
export interface ProjectsHandle {
  /**
   * Insert text at cursor position.
   * @param {React.ChangeEvent<HTMLInputElement>} event
   * @public
   */
  handleLocationFilterChange: (event: React.ChangeEvent<HTMLInputElement>) => void
}

const Projects = forwardRef<ProjectsHandle>((props, ref) => {
  let {id} = useParams<{ id: string }>()
  const [locationFilter, setLocationFilter] = useState('')

  const handleLocationFilterChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setLocationFilter(event.target.value)
  };

  // 对外暴露公共方法
  useImperativeHandle(ref, () => ({
    handleLocationFilterChange
  }))

  return <div>{/* 组件渲染逻辑 */}</div>
})

/**
 * Displays a pageable list of projects or a single (detailed) project if an ID is given via the router.
 * @version 1.0.0
 * @author Django
 */
export default Projects

• 3. 确认注释规范
     需要展示的方法注释必须是/** */格式的块注释，且标注@public标记，不要使用//格式的行注释。

默认不展示组件内部方法是符合组件封装原则的设计，仅作为内部事件处理、不对外暴露的方法属于实现细节，无需展示给组件使用者。

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