選單
GSS 技術部落格
在這個園地裡我們將從技術、專案管理、客戶對談面和大家分享我們多年的經驗,希望大家不管是喜歡或是有意見,都可以回饋給我們,讓我們有機會和大家對話並一起成長!
若有任何問題請來信:gss_crm@gss.com.tw
2 分鐘閱讀時間 (340 個字)

javascript使用jsdoc註解並快速產生api文件

mockuuups-front-view-of-the-macbook-pro-mockup-on-white-table

前言 

JavaScript往往大量使用於WEB專案,而眾所周知JS是一個弱型別且型別可變的腳本語言,這意味著從編輯器中較難直觀的看出這段程式的作用,有些事情只有等到程式真正的運行起來才能夠確定,相信開發人員一定心有戚戚焉。因此良好的註解及開發文件對減少開發時間與降低維護JS代碼成本可說是功不可沒,下列介紹一款工具--JSDoc,透過註解可以自動生成網頁版的文件。 

 安裝

注意安裝JSDoc之前須安裝Node.js 8.15.0以上

使用Command Line全域性安裝JSDoc

npm install -g jsdoc 

本地安裝

npm install jsdoc 

 為程式加上註解

假設我們寫一個JS Function

倘若沒有註解,當開發者使用到該方法時完全看不出是什麼作用

有寫註解,雖可就字面上推測功能,但詳細用法可能還是要看程式邏輯

JSDoc式註解,參數、回傳值型態、用法一目瞭然

從以上範例不難看出註解與註解完整度的重要性

上述的JSDoc格式註解可以在支援的編譯器(如VisualStudio、)中方法上方輸入 /** 自動產出

其他更多Block Tag用法可參考以下連結

...

Use JSDoc: Index

Official documentation for JSDoc 3.

 生成API文件

一樣使用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設定可參考下列連結

 參考資料

...

Use JSDoc: Index

Official documentation for JSDoc 3.

JSDoc 介绍 - 脚本之家

JSDoc是一个根据javascript文件中注释信息,生成JavaScript应用程序或库、模块的API文档 的工具。你可以使用他记录如:命名空间,类,方法,方法参数等。类似JavaDoc和PHPDoc。现在很多编辑器或IDE中还可以通过JSDoc直接或使用插件生成智能提示。从而使开发者很容易了解整个类和其中的属性和方法,并且快速知道如何使用,从而提高开发效率,降低维护成本。
...

GitHub - jsdoc/jsdoc: An API documentation generator for JavaScript.

An API documentation generator for JavaScript. Contribute to jsdoc/jsdoc development by creating an account on GitHub.
保護你的密碼
【jQuery】deferred物件介紹及使用deferred物件解決ajax非同步問題

相關文章

 

評論

尚無評論
已經注冊了? 這裡登入
Guest
2024/03/28, 週四

Captcha 圖像