JSDoc和TypeDoc是JavaScript和TypeScript项目中常用的文档生成工具，通过注释自动生成结构化文档。1. JSDoc适用于JavaScript，使用@param、@returns等标签描述函数参数和返回值类型，通过npm全局安装后运行jsdoc命令生成HTML文档。2. TypeDoc专为TypeScript设计，能自动提取类型、接口、枚举等信息，无需手动标注类型，结合typedoc.json配置入口文件和输出目录，执行npx typedoc生成包含类与方法详情的文档。3. 两者均支持常用注解如@typedef定义复杂类型、@example提供示例、@deprecated标记废弃方法、@see添加参考链接，增强文档可读性。4. 可将文档生成集成到package.json脚本中，配合CI/CD或prebuild钩子自动更新文档，确保代码与文档同步，并可通过GitHub Pages部署在线站点。5. JSDoc适合纯JS项目，TypeDoc更适合TS项目，充分利用类型系统提升维护效率。合理使用注解标签能显著提高团队协作效率和API管理质量。
前端开发中，良好的代码文档能显著提升项目可维护性。JSDoc 和 TypeDoc 是两种主流的 JavaScript 文档生成工具，分别适用于普通 JS 和 TypeScript 项目。它们通过解析代码中的注释自动生成结构化文档，帮助团队协作和 API 管理。
什么是 JSDoc
JSDoc 是一种基于注释的文档生成工具，支持为 JavaScript 函数、类、变量等添加结构化说明。它使用特定语法在注释中描述类型、参数、返回值等信息。
安装 JSDoc 可通过 npm：
npm install -g jsdoc使用时，在代码中添加符合规范的注释：
立即学习“Java免费学习笔记（深入）”；
/** * 计算两个数的和 * @param {number} a - 第一个加数 * @param {number} b - 第二个加数 * @returns {number} 两数之和 */ function add(a, b) { return a + b; }运行命令生成 HTML 文档：
jsdoc add.js会在当前目录生成 out 文件夹，包含可浏览的网页文档。
TypeDoc：TypeScript 的文档利器
TypeDoc 是专为 TypeScript 设计的文档生成器，能自动提取类型定义、接口、枚举等信息，无需手动写类型标签。
安装 TypeDoc：
npm install --save-dev typedoc假设有一个 TypeScript 文件 math.ts：
配置 typedoc.json：
{ "entryPoints": ["src/math.ts"], "out": "docs" }执行生成命令：
npx typedoc会在 docs 目录输出完整文档，包含类、方法、参数类型及说明。
常用注解标签详解
无论是 JSDoc 还是 TypeDoc，都支持一组通用注解标签来增强文档信息：
- @param {type} name - 描述参数名称、类型和说明
- @returns {type} - 说明返回值类型和含义
- @typedef {Object} - 定义复杂类型结构
- @example - 提供使用示例
- @deprecated - 标记已废弃的方法
- @see - 引用其他方法或外部链接
例如：
/** * 用户配置对象 * @typedef {Object} UserConfig * @property {string} name - 用户名 * @property {number} age - 年龄 *//**
- 创建用户
- @param {UserConfig} config - 用户配置
- @example
- createUser({ name: 'Alice', age: 25 }); */ function createUser(config) { ... }
集成到构建流程
为了保持文档与代码同步，建议将文档生成集成进项目 CI/CD 或构建脚本。
在 package.json 中添加脚本：
"scripts": { "docs:js": "jsdoc src/*.js -d docs", "docs:ts": "typedoc", "prebuild": "npm run docs:ts" }这样每次打包前都会自动更新文档。也可以结合 GitHub Pages 自动部署文档站点。
基本上就这些。JSDoc 适合纯 JS 项目，TypeDoc 更适合 TS 项目并能充分利用类型系统。合理使用注释标签，能让生成的文档清晰易读，长期维护更轻松。不复杂但容易忽略。
