如何自制 JS 註釋文檔生成工具

時間 2019-11-09

標籤如何自制註釋文檔生成工具欄目 JavaScript 简体版

原文原文鏈接

對於一個成熟的項目而言，必定須要一個註釋文檔生成工具，咱們有不少可選的開源項目，如jsdoc、yuidocjs 等等，擁有這些強大的工具咱們徹底能夠勝任任何註釋方面的管理了麼？html

一個成熟的開發者都會知道無論怎麼樣的項目都會在不一樣的開發條件下有一些特定條件的需求，因此我今天要講的就是如何自制本身的註釋文檔生成工具。git

以 jsdoc-zero（https://github.com/kahn1990/jsdoc-zero）爲例，基於流行的 jsdoc 規範。github

組件的選擇

命令行工具

首先咱們須要一個命令行工具來方便的執行命令，這裏咱們選擇 colors 組件，若是不喜歡使用 commander 且有能力的人徹底能夠經過 child_process 組件本身封裝執行命令函數。npm

打印組件

若是一直用 console 是否是顏色太單調了呢，不要緊，咱們有 colors 或者 chalk 組件能夠選擇，它會擴展咱們的 console 命令，用來在命令行中顯示其餘顏色。segmentfault

文件相關工具

既然是生成文檔，不可避免的會生成文件夾，因此有 mkdirp 能夠方便快速的幫助咱們生成文件夾。markdown

解析工具

既然是基於 jsdoc 規範，那麼一個用來識別文件註釋的工具就不可少了，這裏咱們選擇 tj 大神的 dox，另外幾乎全部這類工具都默認支持 markdown 文件，因此咱們還須要 marked 來支持 markdown。函數

html 模板

動態生成 html 文件咱們須要一個好的模板引擎，你們怎麼選擇呢？jade 仍是 ejs？工具

這裏我很悲催的跳了 swig 的坑，可能一些同窗沒有據說過這個模板引擎，但它確實很優秀。ui

underscore

最後的最後，咱們須要一個處理數據的工具函數，我選擇 underscore，一是我對他比較熟悉，也寫過一些源碼解析的文章，二是我對比了下 lodash，lodash 與 underscore 的一些細節思想確實不一樣，但從工具使用的角度來說，咱們所使用的一些方法有大部分重疊。spa

工具的結構

咱們在開始以前必定要先肯定項目的大致結構，這是每一個項目的必備過程。

這裏咱們這樣設定，bin 用於放命令相關方法，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 擴展到 underscore 上面：

merge(_, {str: underscoreStr});

以後：

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

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

command.on('--help', function () {
    console.log('\tCommands:\n'.green);
    console.log('\t\t\$ build       建立文檔\n');
    console.log('\tExamples:\n'.green);
    console.log('\t\t\$ doxmate build \-o \<folder\> \-d [\<folder\>,...]\n');
    process.exit(1);
});                                                                                   // 命令行幫助

command.parse(process.argv);

這是用來顯示命令相關的內容，那麼如何執行命令呢，咱們須要：

var cmd = command.args[0];

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

而後對 cmd 參數進行相關判斷：

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('\n\t生成文檔失敗' + err));
                process.exit(1);
            }
        });
        break;
    default:
        console.error(colors.inverse('\n\t提示：不能找到命令 ' + cmd + ' !'));
        return showHelp();
}

以後退出進程 process.exit(0);。具體的相關內容查看 jsdoc-zero/bin/dox。

重點來了

文檔生成工具的重點除了文檔解析以外就是生成文件了，因此咱們能夠看下 jsdoc-zero/lib/default.js：
大致上分爲三個步驟：

創建文件索引
匹配相關文件夾和過濾相關文件夾
衆多路徑問題的處理

其餘的我想你們這麼聰明一看就能夠 hold，而後能夠根據本身的具體項目，更改相關方法定製本身的文檔註釋生成工具了。

PS：爲何「重點來了」這麼短、這麼水？怎麼說呢，樓主這幾天身體不怎麼舒服，千言萬語不知從何提及（jsdoc-zero/lib/default.js 雖然只有短短的幾百行，內部方法也沒多少，可是各個的路徑處理太蛋疼了），具體參考 https://github.com/kahn1990/jsdoc-zero 或者 https://www.npmjs.com/package/jsdoc-zero 。