JSDoc3默认提供了两个模板,默认的模板生成的doc还是比较难看的,另外一个haruki只提供命令行状态下的json输出,不是我们要的。
网络上搜了一下,找到Docstrap,提供多种模板效果,还不错。
1、JSDoc3
JSDoc3这里不说了,下载和配置,见《JSDoc3的简单使用》。
2、Docstrap
官方开源地址:https://github.com/terryweiss/docstrap
下载地址:https://github.com/terryweiss/docstrap/archive/master.zip
解压到比如d:\docstrap
3、生成jsdoc
比如我的js文件放在D:\myjs目录中,要生成的doc目录为D:\jsdocstrap_doc,则执行如下命令:
jsdoc d:\myjs -t d:\docstrap\template -c d:\docstrap\jsdoc.conf.json -d d:\docstrap_doc
执行完毕后,在D盘自动生成docstrap目录,点击其中的index.html可以就可以看到jsdoc了。
我不喜欢在jsdoc里面显示源文件名称和行数信息,所以我想略微配置一下Docstrap的配置信息。
4、配置Docstrap
Docstrap使用的还是jsdoc的配置项,同时新增了几个配置项。打开d:\docstrap\template\jsdoc.conf.json文件,这里面templates那部分就是Docstrap新增的配置项。
{
"tags" : {
"allowUnknownTags" : true
},
"plugins" : ["plugins/markdown"],
"templates" : {
"cleverLinks" : false,
"monospaceLinks" : false,
"default" : {
"outputSourceFiles" : true
},
"systemName" : "DocStrap",
"footer" : "",
"copyright" : "DocStrap Copyright © 2012-2013 The contributors to the JSDoc3 and DocStrap projects.",
"navType" : "vertical",
"theme" : "cerulean",
"linenums" : true,
"collapseSymbols" : false,
"inverseNav" : true
},
"markdown" : {
"parser" : "gfm",
"hardwrap" : true
}
}
解释下其中几个配置项的作用:
- outputSourceFiles:是否输出js源文件,也就是生成的jsdoc里是否显示源js文件的链接。不想让用户看到js源文件的话,这项改成false,或者整个default项删除也行。
- systemName:js产品的名称。也就是生成的jsdoc页面上方的名称。这个改成你自己的。
- copyright:版权信息。
- navType:导航方式。就是页面上方的Classes导航下拉菜单。支持vertical和inline两种方式。建议用vertical。inline我觉得不方便。
- theme:皮肤模板。默认这个就挺好。Docstrap现在提供了13种效果。感兴趣的,可以自己去看看其它效果:https://github.com/terryweiss/docstrap
- linenums:是否显示所在行数。比如当前方法位于js源文件12行。false的话,就不显示这个信息。
- collapseSymbols:是否将类,方法,属性等doc信息以加号的方式收起。
其余的配置项大家自己试试吧,我认为没必要改,这里就不说了。
上面说了,我不想输出js源文件,不想显示行号,而且实际上我就不想显示源文件的任何信息,也就是doc里面不想输出Source那部分信息。
通过outputSourceFiles,linenums的配置不能完全达到要求。所以我将outputSourceFiles改成false,linenums改成false,还要修改一个模板文件。
打开d:\docstrap\template\tmpl\details.tmpl,找到以下部分代码:
<?js if (data.meta) {?>
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<?js= self.linkto(meta.shortpath) ?><?js if (this.navOptions.linenums) {?>, <?js= self.linkto(meta.shortpath, 'line ' + meta.lineno, null, 'sunlight-1-line-' + meta.lineno) ?><?js } ?>
</li></ul></dd>
<?js } ?>
修改成自己想要的,或者直接删除。
贴下效果图:
其实我还是希望可以直接生成JavaDoc那种效果的文档,类似jsdoc toolkit那种效果的,但还没找到办法。如果有朋友知道的话,希望也能告诉我一下,谢谢了先。