使用grunt-jsdoc自動化生成javascirpt文檔

時間 2019-11-08

標籤使用 grunt jsdoc 自動化生成 javascirpt 文檔欄目 Node.js 简体版

原文原文鏈接

背景

Javascript已經成爲一門被人們從新認識的編程語言，因爲大量JS開源框架的出現，利用Javascript開發的項目愈來愈多，愈來愈大。同時，也有愈來愈多Javascript開發問題暴露出來，如性能、網頁加載速度等，其中，Javascript文檔維護也成爲了開發者亟待解決的一個難題。 html

許多現代編程語言都有本身的集成化文檔生成工具，像Java有JavaDoc，.NET有NDoc，PHP有PHPDoc，這些自動化文檔工具能夠根據代碼中的註釋自動生成代碼文檔。 node

NOTE: 我我的使用的是LINUX，因此本文不少命令都是在LINUX下運做的。 git

依賴

JsDoc

實際上，JsDoc是一門用於標註Javascript源代碼的語言。使用包含JsDoc定義的註解，程序員能夠在Javascript註釋中包含API文檔。經過一系列工具進行批量處理，最終生成HTML或者Rich Text Format等格式的API文檔。程序員

目前JsDoc最新版本是3.0。 github

JsDoc Toolkit

JsDoc Toolkit是一個自動化文檔工具，它是發佈在Google code上的一個開源項目，和其餘語言的文檔工具同樣，它能夠自動從Javascript代碼中提取註釋生成格式化文檔。 web

由於JsDoc Toolkit是用Java開發的，所以若是你想要使用JsDoc Toolkit，你的機器上就須要配置JAVA環境。 npm

NOTE:從 2010.07.27 開始，JsDoc Toolkit 2已經中止開發了，所以若是要使用JsDoc的話，仍是推薦採用JsDoc3。編程

Grunt

Grunt是一個基於Node.js的Javascript項目管理和構建自動化工具。目前的穩定版本是0.4.1。數組

NOTE:關於如何在LINUX下安裝GRUNT，請參考我之前編寫過的這篇博文：《在Linux Mint下安裝Grunt》框架

grunt-jsdoc

grunt-jsdoc其實就是一個JsDoc Toolkit的包裝，其配置最後都會傳遞給JsDoc Toolkit做爲參數運行。

grunt-jsdoc是一個Grunt的插件。這個插件集成了JsDoc Toolkit 3，而且你可以經過配置Grunt任務來生成API文檔。

NOTE:這裏有一個和grunt-jsdoc很相似的grunt插件：grunt-jsdoc-plugin，實際上他們是同一個開發者開發，可是區別是grunt-jsdoc是基於JsDoc Toolkit 3而grunt-jsdoc-plugin是基於JsDoc Toolkit 2的。以前由於不知道這個區別繞了很長的一段彎路。

安裝

首先檢查你是否已經安裝好JAVA而且配置好JAVA_HOME這個環境變量了。JsDoc Toolkit是基於JAVA編寫了，運行的時候也須要使用到JAVA環境。若是沒有，LINUX下能夠參考這篇文章安裝和配置： Ubuntu 上使用 OpenJDK 安裝並運行 Tomcat

想要在項目裏面支持grunt-jsdoc其實很簡單。由於自己grunt就是一個基於Node.js的軟件，其插件也是經過npm進行維護的，那麼咱們安裝jsdoc其實很方便，就一行代碼。

npm install grunt-jsdoc --save-dev

grunt-jsdoc的grunt任務配置

任務配置其實也是很是的簡單。在我看來，其實Grunt就只支持兩種任務，分別是基本的Task以及MultiTasks。這二者的區別是基本的Task的任務配置只有一個，而MultiTasks則有多個。大多數的grunt插件任務都是MultiTasks。

Task

API:

grunt.registerTask(taskName, [description, ] taskList)

使用示例：

grunt.registerTask('default', ['jshint', 'qunit', 'concat', 'uglify']);
//  注意看，每個taskList格式是這樣的：「任務名：啓用的任務配置」。經過這樣的形式，咱們能夠指定MultiTasks運行時使用的配置，不然默認狀況下，MultiTasks會依次使用每一個配置去執行一遍任務。
grunt.registerTask('dist', ['concat:dist', 'uglify:dist']);

MultiTasks

API:

grunt.registerMultiTask(taskName, [description, ] taskFunction)

使用示例：

//  log任務有三種不一樣的配置
grunt.initConfig({
  log: {
    foo: [1, 2, 3],
    bar: 'hello world',
    baz: false
  }
});

//  默認狀況下，MultiTasks會依次使用每一個配置去執行一遍任務。
grunt.registerMultiTask('log', 'Log stuff.', function() {
  grunt.log.writeln(this.target + ': ' + this.data);
});

grunt-jsdoc配置

基本語法：

grunt.initConfig({
    jsdoc : {
        dist : {
            src: ['src/*.js', 'test/*.js'], 
            options: {
                destination: 'doc'
            }
        }
    }
});

參數說明：

src: 要自動生成API文檔的源文件路徑數組
jsdoc: jsdoc的bin文件夾目錄
options: jsdoc單獨使用的配置項
- destination：必填，指定文檔輸出路徑
- configure： jsdoc配置文件路徑
- template：文檔模板路徑
- private：是否在文檔中輸出private成員，默認爲true
- 更多參數：參考官方文檔：Command-line arguments to JSDoc

執行任務

基本語法：

grunt taskname

固然，若是你爲某一個MultiTasks任務指定一個目標配置，也是可行的。以上面的MultiTasks中提到的做爲例子就是：

//  運行concat任務，同時指定使用foo做爲目標配置
//  這樣在運行的時候，this.data == foo
grunt concat:foo

JsDoc註解

Namepaths in JSDoc 3

在使用JsDoc以前，首先要了解一個概念就是namepath。本質上講，namepath是JSDoc註釋裏明確變量的實例成員，靜態成員或者內部成員的機制。

namepath的基本語法示例：

MyConstructor
MyConstructor#instanceMember
MyConstructor.staticMember
MyConstructor~innerMember

Tutorials機制

使用Tutorials機制，你能夠對你的Javascript代碼作出更加詳細的，更加複雜的的DEMO頁面。

要啓用Tutorials機制，首先你要現指定一個包含tutorials頁面的文件夾路徑，好比：

jsdoc: {
    dev : {
        src: jsdoc_src, 
        options: {
            private    : false,
            destination: 'dev_release/doc/',
            tutorials  : 'dev_release/demo'
        }
    }
}

而後是時候@tutorial註解，而且指定tutorial的ID。具體來講，一個tutorial的ID其實就是文件名。（ e.g. 好比textbox_index.html的tutorialID就是textbox_index ）

/** 
 *  web.textbox
 *  文本域
 *  @class      textbox 
 *  @memberof   web
 *  @extends    web.formelement
 *  @tutorial   textbox_index
 *  @param      {Object}    options     -   控件配置參數
 *  @param      {Object}    element     -   dom對象
 */
control( 'web.textbox', web.formelement, {} )

各類註解

命名空間，模塊，類聲明，繼承

@class

基本語法：

@class <SomeClassName>

DEMO：

/** 
 *  控件基類
 *  @class      control 
 *  @param      {Object}    options     -   控件配置參數
 *  @param      {Object}    element     -   dom對象
 */
 function Control( /* options,element */ ){  };

@memberof

定義一個符號屬於另一個父符號，這個註解其實很是好用。在Javascript類型繼承實際上是比較複雜的事情的，由於咱們能夠經過編寫代碼生成類構造函數來實現類的定義和繼承。那這個時候，類原型的屬性要怎麼和類型關聯起來呢？就是要經過@memberof這麼一個機制實現。

若是是類型的實例成員，那麼你能夠以這樣的語法格式編寫註釋：@memberof ClassName.prototype或者是@memberof ClassName#。此外還有第三種方式，就是同時使用@memberof和@instance註解。我我的都是使用第三種方式編寫註釋。

基本語法：

@memberof <parentNamepath>

DEMO：

/** 
 *  web.textbox
 *  文本域
 *  @class      textbox 
 *  @memberof   web
 *  @extends    web.formelement
 *  @tutorial   textbox_index
 *  @param      {Object}    options     -   控件配置參數
 *  @param      {Object}    element     -   dom對象
 */
control( 'web.textbox', web.formelement, {
   /**
     *  表單控件值
     *  @public
     *  @instance
     *  @memberof   web.textbox
     *  @member     {Object}    value
     *  @default    null
     *  @example    <caption>get</caption>
     *      var value = ctrl.value();
     *  @example    <caption>set</caption>
     *      ctrl.value( 'your text value' );
     */
    value : function( val ){ }

}）；

@namespace

基本語法：

@namespace [[{<type>}] <SomeName>]

DEMO：

/**
 * My namespace.
 * @namespace
 */
var MyNamespace = {
    /** documented as MyNamespace.foo */
    foo: function() {},
    /** documented as MyNamespace.bar */
    bar: 1
};