title: 你寫的文件別人看得懂嗎？：compodoc
date: 2017-10-15 08:00
categories: Training
keywords:
對程式設計師來說撰寫程式應該是最花時間跟精力的事情，但是撰寫文件卻是一件不輸撰寫程式的工作，尤其是現在這種需求變更越來越頻繁、更新速度越來越快的時代，撰寫文件往往變成只是應付驗收用的工作，所以很多公司都是驗收前再開始撰寫，避免浪費人力跟時間，而這種敷衍的心態也造成系統上線(驗收)後隨著需求不斷的調整與增加，文件跟程式越來越不同步，甚至不再維護文件，所以承接別人的系統應該是程式設計師最討厭的事情。
官方網站：https://compodoc.github.io/website/
GitHub：https://github.com/compodoc/compodoc
compodoc 是一個能夠分析 Angular 程式碼並自動幫我們產生相關網頁文件的工具，透過它可以協助我們產生一份與程式碼同步的文件，接下來我們就直接來時做一次，首先當然就是安裝 compodoc，我們可以透過下列指令將其安裝在 Node.js 全域內供所有專案使用：npm i -g @compodoc/compodoc
或者可以單純安裝到專案內：npm i -d @compodoc/compodoc
接下來我們切換到 Angular 專案目錄下，並透過下列指令來產生文件：compodoc -p src\tsconfig.app.json
我們可以看到 compodoc 會分析 Angular 專案的結構
預設輸出路徑為 documentation 資料夾，可以透過 -d [folder] 參數修改位置
我們可以透過指令 compodoc -s 來啟動內建的網頁伺服器，預設連接埠為 8080，可以透過 -r [port] 來修改。
依照官方文件來看
-s參數應該也會建立網頁，不過目前並沒有效果。
透過瀏覽器瀏覽 http://localhost:8080。
compodoc 產生的是靜態網頁文件，所以也可以直接用瀏覽器開啟。
overview.html
預設的 overview 頁面已經呈現此專案的基本架構
Modules
RouterModule：路由模組
NgModule 夾帶的資料越多頁面也會呈現越多資訊
Components
Info：類別資訊
Source：程式原始碼當然是原始的 TypeScript，而不是編譯過的 JavaScript
Template：樣板原始碼
DOM Tree
Routes
完整的路由路徑
compodoc 也支援 JSDoc 註解，所以我們只要在程式碼做好適當註解，最後就可以一併輸出到文件上，這部分就須依賴大家自己建立良好的習慣，在程式撰寫同時務必加入註解，修改時也須注意註解說明是否需要調整，這樣只要一行指令就可產生一份具有專業水準的說明文件(網站)。
我們可以透過 --theme [theme] 參數來設定主題樣式，完整指令如下：compodoc -p src\tsconfig.app.json --theme [theme]
目前提供主題樣式如下表：
| 參數 | 說明 |
|---|---|
| gitbook (預設) |  |
| laravel |  |
| original |  |
| postmark |  |
| readthedocs |  |
| stripe |  |
| vagrant |  |
| 參數 | 說明 |
|---|---|
--help |
縮寫：-h，輸出使用信息 |
--version |
縮寫：-V，輸出版本號 |
--tsconfig [config] |
縮寫：-p [config]，一個tsconfig.json文件 |
--output [folder] |
縮寫：-d [folder]，存儲生成文檔的位置 |
--extTheme [file] |
縮寫：-y [file]，套用外部主題 |
--name [name] |
縮寫：-n [name]，文件標題 |
--assetsFolder [folder] |
縮寫：-a [folder]，在建立在網頁文件同時也複製外部資源資料夾 |
--open |
縮寫：-o，打開生成的文檔 |
--silent |
縮寫：-t，在靜默模式下，日誌消息不會記錄在控制台中 |
--serve |
縮寫：-s，服務生成的文檔，預設網址為 http://localhost:8080/ |
--port [port] |
縮寫：-r [port]，更改預設網址的連接埠 |
--watch |
縮寫：-w，啟動監看服務，當監看的檔案異動時自動重建網頁 |
--theme [theme] |
選擇要套用的主題，預設為gitbook，可用主題有：laravel、original、postmark、readthedocs、stripe、vagrant |
--name [name] |
縮寫：-n [name]，文件標題 |
| –hideGenerator | 隱藏網頁下方的 Compodoc 圖示 |
| –toggleMenuItems | 關閉默認項目，預設為 all，值：[ modules,components,directives,classes,injectables,interfaces,pipes,additionalPages ] |
| –includes [path] | 引用外部 markdown 檔的路徑 |
| –includesName [name] | 外部標記文件的項目清單名稱，預設為”附加文檔” |
| –coverageTest | 以閾值測試文檔覆蓋的命令，預設為 70 |
| –disableSourceCode | 不要添加原始碼 |
| –disableGraph | 禁用依賴圖的渲染 |
| –disableCoverage | 不要添加文檔覆蓋率報告 |
| –disablePrivateOrInternalSupport | 不要在生成的文檔中顯示 private，@internal 或 Angular 生命週期鉤子 |
