你寫的文件別人看得懂嗎?:compodoc

前言

對程式設計師來說撰寫程式應該是最花時間跟精力的事情,但是撰寫文件卻是一件不輸撰寫程式的工作,尤其是現在這種需求變更越來越頻繁、更新速度越來越快的時代,撰寫文件往往變成只是應付驗收用的工作,所以很多公司都是驗收前再開始撰寫,避免浪費人力跟時間,而這種敷衍的心態也造成系統上線(驗收)後隨著需求不斷的調整與增加,文件跟程式越來越不同步,甚至不再維護文件,所以承接別人的系統應該是程式設計師最討厭的事情。

安裝 compodoc

官方網站: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,可用主題有:laraveloriginalpostmarkreadthedocsstripevagrant
--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 生命週期鉤子

參考資料:https://compodoc.github.io/website/guides/usage.html