背景
前两周接到一个需求，为我们的公共接口库生成一篇文档，主要是老大觉得这么重要的库连篇像样的文档都没有，来一个新人都要口耳相传忒费劲QAQ。在网上搜了些自动化识别js并生成文档的第三方工具，最终选择了JSDoc。
JSDoc功能描述
JSDoc 是一个根据 javascript 文件中注释信息，生成 JavaScript 应用程序或库、模块的 API 文档 的工具。本文就不赘述JSDoc的具体使用了，主要是想讲一下基于JSDoc已有的强大功能，如何再增加一些定（ji）制（lei）的配置，同时带大家一起看一下源码。
先看一下JSDoc生成的文档的样子：
上面这张是用JSDoc的模板工具minama生成的文档，可以看到他的功能有以下几个：
- Home首页，jsdoc支持用一个markdown文档来展示这个页面
- Class、module等分类，jsdoc会通过注释的块标签来识别当前组件属于哪一个类别
- Class里面的F，jsdoc会自动解析类里的function（前提是带注释），并按照注释来展示方法的一些特性
- source，可以看到每个方法里还有source，对应的在哪个文件，多少行，点击还能看到对应的代码
- ...
新增功能
以上这些功能是jsdoc的主要功能，可以说已经很强大了，但是呢，依据业务（老大）的要求，我们的jsdoc新增了如下功能：
- 可以通过config.json文件来配置首页的名称
- 可以在home下添加额外的菜单（jsdoc提供额外的菜单，但是只能跳转到其他外链）
- 可以解析markdown文件，这里说的解析实际上是把遍历出来的markdown文件单独处理，因为jsdoc只能处理js文件，特别是他源码里还写死了
includePattern: '.+\\.js(doc|x)?|md$'，当然这里我们也做了修改 - 将解析出来的markdown文件根据名称放在相应类或者全局文档下面，jsdoc的分类和文件的路径没有任何关系，这导致我们会需要依据文档名称去分类
- 生成总览markdown，这个markdown展示了文档里的所有类和方法，并加上了他们的description和href，使用户能对文档有个初步的了解
- 新增资源文档存放，实际上是将一些静态资源也输出到jsdoc生成的文档目录里
- 对特殊注释做了nav的标识，比如对当注释中只有
未添加注释时，将该分类标红，用来提示开发同学哪些文件需要添加注释了 - ...
JSDoc原理
这里附上一张我之前画的jsdoc的工作原理图，没有深入，只是很简单的做了下分析
可以看到流程图分为了左右两部分，我们一起来看下
- 左上角的入口方法是对jsdoc的配置文件解析、加载日志系统并开始执行文件解析
- 然后是通过你配置的入口文件，对文件进行一个递归遍历，分别是创建解析方法、解析文件、生成结果，最终会生成一个AST
- 然后将生成的结果传给generateDocs方法，通过判断配置文件里是否有模板地址来选择将结果交给谁
- 这里我们用了docdash，实际上我们的大部分功能增加和修改都是在docdash里去做的，将jsdoc给的结果去做一些可视化的呈现。
- docdash会暴露一个publish方法，依次会去生成左侧的导航栏、各个解析好的html和markdown文件，将这些文件最终放在配置文件里写的输出目录里
源码分析
node_modules/jsdoc/lib/jsdoc/config.js中做了includePattern的默认配置，这里我们给正则添加md结尾的识别
接下来直接到了渲染部分，我们用到了docdash模板，以上的代码是docdash的publish.js里来渲染nav模块，我们可以看到除过global，其他都是用buildMemberNav方法去渲染，上边还有判断是否是全局文档，通过文件名称的前缀为GLobal_来识别，把这部分放在对应的目录下面
这块呢我们实现了
- 可以在home下添加额外的菜单
- 可以通过config.json文件来配置首页的名称
- 将
Global_前缀的markdown文件放在全局目录下
这块呢是在上面我们看到的buildMemberNav方法里添加的用来生成总览的方法，对结果遍历生成一个表格来展示所有的方法和简述。还有一部分是对注释的内容做了判断来标识未写注释的文件，以及通过文件名来判断是否有文件名前缀的markdown文件和某类名一样的情况，有的话会把这个markdown文件放在对应的类下面，这块就不展示了
- 生成总览markdown
- 对特殊注释做了nav的标识
- 将文件名前缀和类名一样的markdown文件放在对应的类目录下
这块是通过node的fs.writeFileSync去将各个类及md文件输出成html文件，包含了首页、总览、md及各个模块
jsdoc会对文件进行遍历并解析，我们前面在includePattern中放开了对md文档的限制，在这块，需要对这类文件做处理，否则jsdoc会将md文件按照js文件的方式解析。
这里我们新建了一个全局变量用来存储这些md文件的路径，最终的docdash里去生成这些md文件对应的html
- 可以解析markdown文件
以上是对jsdoc输出做的一些功能上的添加，希望这些分析能对大家生成一份js文档有帮助。
