对于一个成熟的项目而言，一定需要一个注释文档生成工具，我们有很多可选的开源项目，如jsdoc、yuidocjs 等等，拥有这些强大的工具我们完全可以胜任任何注释方面的管理了么？

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

以 jsdoc-zero（https://github.com/kahn1990/jsdoc-zero）为例，基于流行的 jsdoc 规范：

JSDOC-ZERO

安装 (Installation)

安装 JSDOC-ZERO 为全局工具：

$ npm install jsdoc-zero -g

使用 (Use)

建立配置文件 (Create configuration file)

首先在项目根目录下建立 dox.config.json 文件，默认内容为：

{
  "name"     : "default",
  "version"  : "0.0.1",
  "source"   : {
    "include": [
      "lib"
    ],
    "exclude": [
      "node_modules"
    ],
    "suffix" : [
      ".js"
    ],
    "output" : "doc/dox"
  }
}

其中含义：

name : 项目名称
version : 版本号码
source
- include : 待检查目录的集合，默认检查 lib 文件夹
- exclude : 需要过滤的目录集合，默认过滤 node_modules 文件夹
- suffix : 待检查文件的后缀名，默认检查 js 文件和 md 文件
- output : 输出目录，默认输出 doc/dox

使用的时候直接在项目根目录下执行 jdz build。

命令行使用 (Command line usage)

为了简单直白，我只保留了 build 功能，相关的参数也只有 -o 和 -d：

-o : 指定输出目录，如 -o doc/box
-d : 指定待检查目录的集合，如 -d ['lib', 'server']

在命令行直接执行：jdz build -o doc/box -d ['lib', 'server']，并且 -o 缺省为默认配置文件中的 doc/dox，-d 缺省为默认配置文件中的 ['lib']。

组件的选择

命令行工具

首先我们需要一个命令行工具来方便的执行命令，这里我们选择 colors 组件，如果不喜欢使用 commander 且有能力的人完全可以通过 child_process 组件自己封装执行命令函数。

打印组件

如果一直用 console 是不是颜色太单调了呢，没关系，我们有 colors 或者 chalk 组件可以选择，它会扩展我们的 console 命令，用来在命令行中显示其他颜色。

文件相关工具

既然是生成文档，不可避免的会生成文件夹，所以有 mkdirp 可以方便快速的帮助我们生成文件夹。

解析工具

既然是基于 jsdoc 规范，那么一个用来识别文件注释的工具就不可少了，这里我们选择 tj 大神的 dox，另外几乎所有这类工具都默认支持 markdown 文件，所以我们还需要 marked 来支持 markdown。

html 模板

动态生成 html 文件我们需要一个好的模板引擎，大家怎么选择呢？ jade 还是 ejs？这里我很悲催的跳了 swig 的坑，可能一些同学没有听说过这个模板引擎，但它确实很优秀。

underscore

最后的最后，我们需要一个处理数据的工具函数，我选择 underscore，一是我对他比较熟悉，也写过一些源码解析的文章，二是我对比了下 lodash，lodash 与 underscore 的一些细节思想确实不同，但从工具使用的角度来讲，我们所使用的一些方法有大部分重叠。

-1625行，解开 underscore.js 的面纱 - 第一章 -1625行，解开 underscore.js 的面纱 - 第二章 -1625行，解开 underscore.js 的面纱 - 第三章 -1625行，解开 underscore.js 的面纱 - 第四章 -1625行，解开 underscore.js 的面纱 - 第五章 -1625行，解开 underscore.js 的面纱 - 第六章

工具的结构

我们在开始之前一定要先确定项目的大体结构，这是每个项目的必备过程。捕获.PNG ! 这里我们这样设定，bin 用于放命令相关方法，lib 放主要方法，其他的看字面意思就知道做什么的了，不敖述了。

注意 (Careful)

JSDOC-ZERO 每次生成文档的时候都会清空 输出目录 下的所有文件。 JSDOC-ZERO every time the document will be generated when the output directory of all the documents

依赖

依赖于 TJ 的 dox。

PS：。

magicdawn 1楼•8 年前

支持一下