Debian环境下进行 JavaScript 文档编写
一 环境准备
- 在 Debian 上安装 Node.js 与 npm，为文档工具提供运行环境：
- 安装：
sudo apt update && sudo apt install nodejs npm
- 验证：
node -v、npm -v
- 选择并安装文档生成工具（全局或本地安装均可）：
- JSDoc：
npm i -D jsdoc
- ESDoc：
npm i -D esdoc
- Documentation.js：
npm i -D documentation
- 建议使用 VS Code 并配合 ESLint、Prettier 等扩展，提升注释与代码一致性。
二 注释规范与示例
- 采用 JSDoc 编写标准化注释，便于工具解析并生成结构化文档。
- 常用标签：
- @param：参数及类型
- @returns：返回值及类型
- @example：可运行示例
- @see：参考链接
- 示例：
/**
- 两数相加
- @param {number} a - 第一个数
- @param {number} b - 第二个数
- @returns {number} 两数之和
- @example
- // returns 3
- add(1, 2);
*/
function add(a, b) {
return a + b;
}
- 提示：保持注释与代码同步，示例应覆盖常见用法与边界情况。
三 文档生成工具与配置
- 常用工具对比与命令
| 工具 |
安装 |
常用命令 |
输出与特点 |
| JSDoc |
npm i -D jsdoc |
npx jsdoc src -c jsdoc.json -d docs |
生成 HTML API 文档，标签体系完备 |
| ESDoc |
npm i -D esdoc |
npx esdoc -c esdoc.json |
支持 ES6+，插件生态友好 |
| Documentation.js |
npm i -D documentation |
npx documentation build src -f html -o docs |
支持 Markdown 输出，灵活可定制 |
- 最小可用配置示例
- JSDoc（jsdoc.json）
{
“source”: { “include”: [“src”], “exclude”: [“node_modules”] },
“opts”: { “destination”: “./docs”, “recurse”: true }
}
- ESDoc（esdoc.json）
{
“source”: “./src”,
“destination”: “./docs”,
“plugins”: [{ “name”: “esdoc-standard-plugin” }]
}
- 生成后检查 docs 目录是否包含 index.html 或相应静态站点文件。
四 集成到开发与发布流程
- 在 package.json 添加脚本
{
“scripts”: {
“docs”: “jsdoc src -c jsdoc.json -d docs”,
“docs:serve”: “http-server docs -p 8080”
}
}
- 本地预览：
npm run docs && npm run docs:serve
- 持续集成（GitHub Actions 示例）
- 在
.github/workflows/docs.yml 中：
- 步骤：安装依赖（
npm ci）、生成文档（npm run docs）、部署到 GitHub Pages（使用 actions/upload-pages-artifact / actions/deploy-pages）
- 质量保障
- 将文档检查加入 PR 门禁（例如：存在未闭合的 JSDoc 标签即失败）
- 定期审查与更新示例，确保与代码一致。
五 打包发布到 Debian 的注意事项
- 若计划将 Node.js 模块打包进 Debian 发行版，需遵循 Debian JavaScript Policy 与 Node.js 打包指引，并与 Debian JavaScript 团队协调维护。
- 参考资源：
- Policy：https://wiki.debian.org/JavaScript/Policy
- Nodejs：https://wiki.debian.org/Nodejs
- 团队联系：debian-js@lists.debian.org，IRC：#debian-js（oftc.net）
- 说明：本节面向“将 JS 库打包为 Debian 包”的场景；若仅在 Debian 上开发并托管文档（如 GitHub Pages），可忽略该部分。