如何自制 JS 注释文档生成工具

一个成熟的开发者都会知道不管怎么样的项目都会在不同的开发条件下有一些特定条件的需求，所以我今天要讲的就是如何自制自己的注释文档生成工具。

组件的选择

命令行工具

打印组件

文件相关工具

解析工具

html 模板

动态生成 html 文件我们需要一个好的模板引擎，大家怎么选择呢？jade 还是 ejs？

underscore

工具的结构

我们在开始之前一定要先确定项目的大体结构，这是每个项目的必备过程。

这里我们这样设定，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>')
    
    .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();
}

重点来了

1. 建立文件索引
2. 匹配相关文件夹和过滤相关文件夹
3. 众多路径问题的处理

其他的我想大家这么聪明一看就可以 hold，然后可以根据自己的具体项目，更改相关方法定制自己的文档注释生成工具了。

其他参考