JSDoc3+Docstrap的使用

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那种效果的，但还没找到办法。如果有朋友知道的话，希望也能告诉我一下，谢谢了先。