apidoc 是基于 node.js 的命令行工具，需配合 atom 注释规范和手动执行命令生成 api 文档；atom 无 ast 解析能力，无法原生支持自动文档生成。
apidoc 是 Atom 里生成 API 文档最直接可用的方案，但它不是 Atom 原生插件，而是基于 Node.js 的命令行工具，需要配合 Atom 的注释规范和脚本调用才能跑通。直接装个“文档生成插件”就想点一下出 HTML？基本行不通。
为什么不能只靠 Atom 插件自动生成文档？
Atom 本身不解析 JS/CoffeeScript 语义，它没有内置的 AST 解析器。像 apidoc、jsdoc 这类工具，必须读源码、识别注释块、提取参数/返回值/类结构，再渲染成页面——这得靠独立 CLI 工具完成。Atom 只能帮你写对注释、快速触发命令、预览结果。
apidoc 的最小可行流程（Atom 配合版）
你得手动搭一层胶水，但不用写构建脚本也能跑起来：
- 在项目根目录运行
npm init -y && npm install --save-dev apidoc - 按
apidoc规范写注释（必须是/** */块，且紧贴函数/类声明上方） - 在 Atom 里打开终端（
Ctrl+`），执行npx apidoc -i src/ -o docs/（src/是你放 JS 文件的目录） - 生成的
docs/index.html可用markdown-preview-plus或浏览器直接打开
注意：apidoc 不支持 ES6 class 语法的自动识别，如果写的是 class Editor { initialize() { ... } }，它会漏掉方法；必须拆成独立函数或加 @name Editor#initialize 手动指定作用域。
Docblockr 能帮你省下 80% 的注释时间
它不生成文档，但能确保你写的注释格式正确、字段齐全，避免 apidoc 提取失败：
- 光标停在函数名上方，输入
/**+Tab，Docblockr 自动补全@param和@returns - 如果函数有解构参数，比如
({ theme, packages })，它不会自动展开，得手动补成@param {Object} options+@param {string} options.theme - 配置里关掉
Auto-Expand On Enter，否则回车换行时会多插一堆*，反而干扰apidoc解析
错误示例：/** @param theme {string} */ —— apidoc 会忽略这个参数，因为缺少冒号前的空格和大括号位置不对；正确写法是 @param {string} theme。
别跳过 .apidoc.json 配置文件
默认生成的文档很简陋，连标题都是 “API Documentation”。加个配置文件能立刻提升专业感：
{
"name": "my-editor-plugin",
"version": "1.2.0",
"description": "Atom 插件 API 接口说明",
"title": "My Plugin API Docs",
"url": "https://github.com/you/my-plugin"
}
放在项目根目录，apidoc 会自动读取。漏掉 version 字段会导致生成失败，报错信息是 Error: No valid version found in package.json or apidoc.json —— 它其实是在找 version，不是让你删掉这行。
真正容易被忽略的点：生成文档后，apidoc 不校验 JS 语法是否合法。如果某个函数注释写对了，但代码里有 const foo = ; 这种语法错误，它照样生成 HTML，但文档里对应接口会消失——因为解析器在读 JS 文件时直接跳过了整块。所以每次生成前，先确保代码能过 eslint 或 node -c 检查。
