jsdoc2md 的 template 使用

最新在写js文档. 开始的时候是用jsdoc 将 js文件注释转换成 html. 后期公司要求 将js文件的注释转换成markdown ,因此就研究了下jsdoc-to-markdown
可以将js的注释转换成markdown 文件

安装

安装很简单,执行

npm install --save-dev jsdoc-to-markdown

转换

1.假设example.js 内容如下

/**
 * A quite wonderful function.
 * @param {object} - Privacy gown
 * @param {object} - Security
 * @returns {survival}
 */
function protection (cloak, dagger) {}

2. 转换命令

命令行执行 ,将markdown文本输出到屏幕上

$ jsdoc2md example.js

要是想将文件输出到文件,执行

$ jsdoc2md example.js > readme.md

3.获取的markdown 文件

## protection(cloak, dagger) ⇒ survival
A quite wonderful function.

**Kind**: global function

| Param  | Type                | Description  |
| ------ | ------------------- | ------------ |
| cloak  | object | Privacy gown |
| dagger | object | Security     |

官方文档地址

更多的使用我们,我们可以看官方的wiki

重要参数 --template

官方文档对该参数列举了一个例子

如何使用命令

$ jsdoc2md --template jsdoc2md/README.hbs lib/*.js

该项目handbrake-js 使用上面命令生成的js文档.

这里就到重点了. README.hbs 文件如何编写.

jsdoc2md currently uses [handlebars](http://handlebarsjs.com/) to generate the output. The partials and helpers involved in creating the output are managed by the [dmd](https://github.com/jsdoc2md/dmd) project.

The default template content is simply `'{{>main}}'`, which renders the output of [this handlebars partial](https://github.com/jsdoc2md/dmd/blob/master/partials/main.hbs). So, a README template could be created by dropping `{{>main}}` into your standard README structure. Step by step tutorial:

这里我们就说重点的, 如果jsdoc2md不使用 --template参数连接用户自定义的 hbs文件 ,那么就想使用默认的默认文件,该文件中只有一行 代码.

{{>main}}

看到上面是不是一脸懵逼. 这是个什么东西. 我也研究了老半天,这其实就是项目 dmd的一个命令 .

 hbs文件只能写dmd 命令吗?
 其实我们可以把hbs 文件理解 md 语法和 dmd语法的组合体
其中 hbs 的 md 相当于 解析js文件额外添加的解释说明

具体可研究[handbrake-js](https://github.com/75lb/handbrake-js)项目

dmd的具体使用

该小结题目中连接的是dmd命令如何使用.

这里大概解析下

{{>main}}

文中的{{>main}}其实对应的是dmd项目下,main.hbs 文件
我们看看该文件的内容

{{>main-index~}}
{{>all-docs~}}

又出现了两个命令
{{>main-index~}}对应的是main-index.hbs
>all-docs~对应的是all-docs.hbs

如果我们定义一个文件test.hbs代码如下

{{>main-index~}}
{{>all-docs~}}

我们运行

$ jsdoc2md --template test.hbs example.js > readme.md

其实等同于

$ jsdoc2md example.js > readme.md

因为 jsdoc2md 默认的链接文件内容是{{>main}}, 而{{>main}} 命令其实就是{{>main-index~}} 和{{>all-docs~}} 两个命令组成的

命令如何工作的,由于作者水平有限就不讲了.这里只教大家基本的.其他的命令需要大家看源码自行查阅.这里只列举下基本使用的

{{>main}}
{{>main-index~}}
{{>all-docs~}}
{{#orphans ~}}
{{>docs~}}
{{/orphans~}}
{{>header~}}
{{>body}}
{{>member-index~}}
{{>separator~}}
{{>members~}}