注意安裝JSDoc之前須安裝Node.js 8.15.0以上
使用Command Line全域性安裝JSDoc
npm install -g jsdoc
本地安裝
npm install jsdoc
假設我們寫一個JS Function
倘若沒有註解,當開發者使用到該方法時完全看不出是什麼作用
有寫註解,雖可就字面上推測功能,但詳細用法可能還是要看程式邏輯
JSDoc式註解,參數、回傳值型態、用法一目瞭然
從以上範例不難看出註解與註解完整度的重要性
上述的JSDoc格式註解可以在支援的編譯器(如VisualStudio、)中方法上方輸入 /** 自動產出
其他更多Block Tag用法可參考以下連結
一樣使用CLI
若之前全域性安裝
jsdoc yourJavaScriptFile.js
若本地安裝
/path/to/jsdoc yourJavaScriptFile.js
執行後會在當前工作目錄產生out資料夾,資料夾內可找到生成的API文件
JsDoc生成的網頁版文件
另外也可以使用Config檔對進行更多生成設定
{ "tags": { "allowUnknownTags": true }, "source": { "include": [ "BestControlApi"], "includePattern": ".+\\.js(doc)?$", "excludePattern": "(^|\\/|\\\\)_" }, "plugins": [], "templates": { "cleverLinks": false, "monospaceLinks": false } }
使用配置文件/path/to/my/conf.json,為./src目錄的中檔案生成文件,並保存到./docs目錄中
jsdoc src -r -c /path/to/my/conf.json -d docs
JSDoc CLI參數及更多Config設定可參考下列連結