摘要：組件的選擇命令行工具首先我們需要一個(gè)命令行工具來方便的執(zhí)行命令，這里我們選擇組件，如果不喜歡使用且有能力的人完全可以通過組件自己封裝執(zhí)行命令函數(shù)。

對于一個(gè)成熟的項(xiàng)目而言，一定需要一個(gè)注釋文檔生成工具，我們有很多可選的開源項(xiàng)目，如jsdoc、yuidocjs 等等，擁有這些強(qiáng)大的工具我們完全可以勝任任何注釋方面的管理了么？

一個(gè)成熟的開發(fā)者都會知道不管怎么樣的項(xiàng)目都會在不同的開發(fā)條件下有一些特定條件的需求，所以我今天要講的就是如何自制自己的注釋文檔生成工具。

以 jsdoc-zero（https://github.com/kahn1990/jsdoc-zero）為例，基于流行的 jsdoc 規(guī)范。

首先我們需要一個(gè)命令行工具來方便的執(zhí)行命令，這里我們選擇 colors 組件，如果不喜歡使用 commander 且有能力的人完全可以通過 child_process 組件自己封裝執(zhí)行命令函數(shù)。

如果一直用 console 是不是顏色太單調(diào)了呢，沒關(guān)系，我們有 colors 或者 chalk 組件可以選擇，它會擴(kuò)展我們的 console 命令，用來在命令行中顯示其他顏色。

既然是生成文檔，不可避免的會生成文件夾，所以有 mkdirp 可以方便快速的幫助我們生成文件夾。

既然是基于 jsdoc 規(guī)范，那么一個(gè)用來識別文件注釋的工具就不可少了，這里我們選擇 tj 大神的 dox，另外幾乎所有這類工具都默認(rèn)支持 markdown 文件，所以我們還需要 marked 來支持 markdown。

動態(tài)生成 html 文件我們需要一個(gè)好的模板引擎，大家怎么選擇呢？jade 還是 ejs？

這里我很悲催的跳了 swig 的坑，可能一些同學(xué)沒有聽說過這個(gè)模板引擎，但它確實(shí)很優(yōu)秀。

最后的最后，我們需要一個(gè)處理數(shù)據(jù)的工具函數(shù)，我選擇 underscore，一是我對他比較熟悉，也寫過一些源碼解析的文章，二是我對比了下 lodash，lodash 與 underscore 的一些細(xì)節(jié)思想確實(shí)不同，但從工具使用的角度來講，我們所使用的一些方法有大部分重疊。

1625行，解開 underscore.js 的面紗 - 第一章

1625行，解開 underscore.js 的面紗 - 第二章

1625行，解開 underscore.js 的面紗 - 第三章

1625行，解開 underscore.js 的面紗 - 第四章

1625行，解開 underscore.js 的面紗 - 第五章

1625行，解開 underscore.js 的面紗 - 第六章

我們在開始之前一定要先確定項(xiàng)目的大體結(jié)構(gòu)，這是每個(gè)項(xiàng)目的必備過程。

這里我們這樣設(shè)定，bin 用于放命令相關(guān)方法，lib 放主要方法，其他的看字面意思就知道做什么的了，不敖述了。

我們先從如何寫命令開始，首先我們先引入需要的組件

var command       = require("commander"),
    path          = require("path"),
    colors        = require("colors"),
    _             = require("underscore"),
    underscoreStr = require("underscore.string"),
    chalk         = require("chalk"),
    mkdirp        = require("mkdirp"),
    fs            = require("fs"),
    merge         = require("../lib/merge"),
    dox           = require("../lib/default");

然后將 underscore.string 擴(kuò)展到 underscore 上面：

merge(_, {str: underscoreStr});

之后：

command
    .version(
        console.log(`
        name: ${chalk.green(loadConfigFiled.name)}
        version: ${chalk.yellow(loadConfigFiled.version)}
        `)
    )
    .usage("")
    .command("build")
    .description("開始生成文檔")
    .option("-d ", "輸入文件夾")
    .option("-o ", "輸出文件夾");                                // 命令行工具版本展示

console.log("------------------------------------------------------------".rainbow);
/**
 * 展示幫助信息函數(shù)
 */
var showHelp = function () {
    process.stdout.write(command.helpInformation());
    command.emit("--help or -h");
    process.exit(1);
};

command.on("--help", function () {
    console.log("	Commands:
".green);
    console.log("		$ build       創(chuàng)建文檔
");
    console.log("	Examples:
".green);
    console.log("		$ doxmate build -o  -d [,...]
");
    process.exit(1);
});                                                                                   // 命令行幫助

command.parse(process.argv);

這是用來顯示命令相關(guān)的內(nèi)容，那么如何執(zhí)行命令呢，我們需要：

var cmd = command.args[0];  

來獲取我們在命令行輸出的內(nèi)容，如我輸入jdz build，則 cmd==>build。

然后對 cmd 參數(shù)進(jìn)行相關(guān)判斷：

switch (cmd) {
    case "build":
        if (!judgeCmdExistence(cmd)) showHelp();

        testBuildCommand(process.argv.slice(3));
        //process.exit(1);
        loadConfigFiled.source.exclude = _.map(loadConfigFiled.source.exclude, function (item) {
            return _.str.strRight(path.resolve(item),loadConfigFiled.projectHomePath).substring(1);
        });
        dox(loadConfigFiled, function (err) {
            if (err) {
                console.log(chalk.blue.bgRed.bold("
	生成文檔失敗" + err));
                process.exit(1);
            }
        });
        break;
    default:
        console.error(colors.inverse("
	提示：不能找到命令 " + cmd + " !"));
        return showHelp();
}

之后退出進(jìn)程 process.exit(0);。具體的相關(guān)內(nèi)容查看 jsdoc-zero/bin/dox。

文檔生成工具的重點(diǎn)除了文檔解析之外就是生成文件了，所以我們可以看下 jsdoc-zero/lib/default.js：
大體上分為三個(gè)步驟：

建立文件索引

匹配相關(guān)文件夾和過濾相關(guān)文件夾

眾多路徑問題的處理

其他的我想大家這么聰明一看就可以 hold，然后可以根據(jù)自己的具體項(xiàng)目，更改相關(guān)方法定制自己的文檔注釋生成工具了。

PS：為什么“重點(diǎn)來了”這么短、這么水？怎么說呢，樓主這幾天身體不怎么舒服，千言萬語不知從何說起（jsdoc-zero/lib/default.js 雖然只有短短的幾百行，內(nèi)部方法也沒多少，但是各個(gè)的路徑處理太蛋疼了），具體參考 https://github.com/kahn1990/jsdoc-zero 或者 https://www.npmjs.com/package/jsdoc-zero 。

http://usejsdoc.org/

http://yui.github.io/yuidoc/

http://jashkenas.github.io/docco/

http://jsdox.org/

https://github.com/senchalabs/jsduck/