TypeDoc无法生成未导出函数文档求助及最佳实践咨询

一、解决typedoc-plugin-not-exported未生效的问题 #

按以下步骤逐一排查和修复：

1. 验证插件版本兼容性
   typedoc-plugin-not-exported的版本需与TypeDoc 0.24.8匹配。执行以下命令安装适配版本（插件v2.x系列适配TypeDoc 0.24.x）：

   npm install typedoc-plugin-not-exported@^2.0.0 --save-dev
   

2. 检查typedoc.json配置正确性
   确保配置文件中正确引入插件，且指定了完整的扫描范围：

   {
     "entryPoints": ["./src/**/*.ts"],
     "plugins": ["typedoc-plugin-not-exported"],
     "out": "./docs"
   }
   

   运行TypeDoc时确保使用该配置：typedoc --options typedoc.json

3. 确认@notExported注解的正确使用
   注解必须放在未导出函数/类的标准JSDoc注释中，示例：

   /**
    * 这是一个未导出的工具函数
    * @notExported
    */
   function internalUtil() {
     // 函数逻辑
   }
   

   注意：不能使用单行注释（//），必须用多行JSDoc格式（/** ... */）。

4. 确保TypeDoc扫描到目标文件
   运行TypeDoc时明确指定包含未导出代码的文件或目录，比如：

   typedoc src/utils/ src/core/
   

   同时检查tsconfig.json的include字段，确保覆盖所有需要扫描的文件：

   {
     "include": ["src/**/*.ts"]
   }
   

5. 排查冲突配置
   如果TypeDoc配置中设置了exclude字段，确保未排除目标文件；另外，禁用其他可能干扰的插件，先单独测试typedoc-plugin-not-exported是否生效。

二、TypeScript生成源码文档的最佳实践 #

1. 规范JSDoc注释

   • 使用标准标签：@param、@returns、@throws、@example、@internal等，注释聚焦于“为什么这么做”而非“做了什么”（代码逻辑由TS类型和实现体现）
   • 避免冗余：利用TS类型声明替代重复的类型注释，比如参数类型无需在@param中重复写

2. 合理控制文档范围

   • 对外API必须导出并完善注释，内部未导出代码仅在需要时添加@notExported或@internal标记
   • 使用TypeDoc的--excludeInternal参数控制是否显示内部代码文档，平衡文档简洁性和完整性

3. 优化TypeDoc配置

   • 按模块组织entryPoints，让文档结构与代码架构一致
   • 选择合适的主题（比如默认的Markdown或HTML主题），添加自定义标题、导航提升可读性
   • 启用categorizeByGroup选项，按类型（函数、类、接口等）自动分类

4. 自动化与同步

   • 将文档生成加入CI/CD流程，每次代码提交自动重新生成文档，确保文档与代码同步
   • 提交代码时检查注释完整性，可配合ESLint的jsdoc插件强制执行注释规范

5. 增强文档实用性

   • 为复杂逻辑添加@example示例代码，方便使用者快速理解
   • 使用@see标签关联相关的函数、接口或业务逻辑，提升文档关联性

内容的提问来源于stack exchange，提问作者Papp Zoltán