compodoc管理angular项目的文档

compodoc管理angular项目的文档

1. 安装

// npm本地安装
npm install --save-dev @compodoc/compodoc

全局安装也行，（不过mac上我报错没有权限，所以就在没试了）
接着在package.json中的script对象中添加下面代码

    "compodoc": "npx compodoc src -p tsconfig.xxxx.json "

注意！！！ 代码中的xxxx表示你项目中的tsconfig是存在某个json中，当你的xxxx不是最终config文件时，就会出现下面的报错

[16:18:04] No configuration file found, switching to CLI flags.
[16:18:04] Using provided source folder
[16:18:04] Using tsconfig file : /Users/suzhijie/myWorkSpace/my-project/tsconfig.app.json
[16:18:04] Searching package.json file
// config正确时应该是下面的内容
[16:19:30] No configuration file found, switching to CLI flags.
[16:19:30] Using provided source folder
[16:19:30] Using tsconfig file : /Users/suzhijie/myWorkSpace/my-project/tsconfig.base.json
[16:19:30] Including      : /Users/suzhijie/myWorkSpace/my-project/src/.DS_Store
[16:19:30] Including      : /Users/suzhijie/myWorkSpace/my-project/src/favicon.ico
[16:19:30] Including      : /Users/suzhijie/myWorkSpace/my-project/src/hmr.ts
[16:19:30] Including      : /Users/suzhijie/myWorkSpace/my-project/src/index.html
。。。。。。。。

2. 运行

compodoc的好处就是本地启动只需要调用compodoc -s就能在8080端口运行
当一切安装好以后会出现下面的log代表完成了

TypeScript version used by Compodoc : 2.9.1

TypeScript version of current project : 3.9.5

Node.js version : v12.18.3

Operating system : macOS Catalina

[15:52:11] No configuration file found, switching to CLI flags.
[15:52:11] Serving documentation from ./documentation/ at http://127.0.0.1:8080

之后打开就大功告成！！

3. 问题

• 当overview中为空时你一定要去看tsconfig是否出问题即可，根源应该是compodoc识别不了extends这个keyword。
• 注释书写标准是以jsDoc为模板，所以文档中是不会识别类似以下注释

/*
 * unsupported comment
 */

/*
  unsupported comment
 */

// unsupported comment

• tag仅支持JSDoc中的部分

tag	备注
@returns	描述返回值
@ignore	表示标记的内容永远不会出现在文档中
@param	定义一个参数的类型和描述
@link	定义链接另一个方法、文档或外部链接
@example	定义一个示例用法