0.0.6 • Published 11 years ago
doc-ring v0.0.6
这是一个专门用于生成Javascript文档的工具。只要注释文档遵循“jsdoc3”规范，就可以生成一份漂亮的文档。
安装
$ npm install doc-ring配置项
- tutorials {Array} 教程、指南的路径，一般是README.md的markdown文件
- src {Array} 源文件路径
- dist {string} 输出文档的目录
WIKI
Hello World
创建项目
新建一个目录取名“hello-doc”，安装好doc-ring和gulp：
$ npm install doc-ring gulp在“hello-doc”根目录下创建“script”目录存放JS脚本，再新建一个“gulpfile.js”文件，现在目录结构是这样的：
/hello-doc
/script
gulpfile.js书写代码和注释
在“script”目录下创建一个JS文件，取名为“foobar.js”，我们会以此文件作为源，读取其中的注释并生成文档，所以需要向它书写一些注释。
doc-ring遵循jsdoc3规范，作为演示只需要书写一个模块、一个属性和一个方法就好，这里使用AMD方式定义一个模块。
/**
* 一些描述{@link module:main/room}
* @module foobar
* @property {Object} lobal 全局对象
*/
define(function(){
return {
/**
* @method
* @description
* 方法的一些描述
* @param {string} pm 传入的参数说明
*/
doSomething: function(pm){}
};
})构建和部署
回到“gulpfile.js”文件，书写如下代码：
var docRing = require('./src');
var gulp = require('gulp');
gulp.task('default', function() {
docRing({
src: ['./script/**/*.js'],
dist: './build'
});
});我们将输出文档定义在hello-doc目录下的“build”中。
现在在命令行中运行gulp即可输出文档：
$ gulp现在根目录下应该会出现一个“build”目录，然后可以将它复制到apache服务器中运行，或将“build”目录建成一个静态文件服务器即可查看文档。
首页和教程文档
API文档有一个默认首页，用户也可以添加自定义首页。首页中可以放置对API库的综述等内容。
自定义的首页必须是一个markdown文件，只要将此文件路径包含在src配置项中即可。
docRing({
src: ['test/*.js', 'README.md'],
dist: './build'
})教程（tutorials）是针对一些特定主题的文档，例如angular的tutorial文档，教程可以有多个，每个教程文档必须是markdown格式的文件，有专门的tutorials配置项用于指定教程文件。
docRing({
tutorials: ['test/tutorials/*.md'],
src: ['test/*.js'],
dist: './build'
})支持的标签
@abstract|@virtual定义抽象成员，必须被继承并实现。@access成员可访问级别（private、public、protected）。@alias符号的别名。@augments|@extends如果一个类继承自一个父类，可使用此标签。@author标注作者名字。@callback定义回调函数。@class|@constructor可以使用new关键字实例化的类。@classdesc和类有关的描述文字。@deprecated此符号已被废弃。@description|@desc符号的描述@event定义事件。@example为某个条目提供示例代码。@exports某个成员会被JS模块暴露。@fires|@emits某个方法可能会触发的事件。@function|@func|@method定义一个函数或对象的方法。@global定义一个全局对象。@inner定义内部成员。@instance定义实例成员。@kind符号的类型@lends将对象字面量标记为某类的成员。@memberof某个符号隶属于另一个符号。@module定义一个JS模块。@name定义一个符号的名字。@override子类覆写了父类的成员。@param|@arg|argument函数的参数。@private定义私有成员。@property定义一个属性。@protected定义某个符号的可访问性为“受保护”的。@public定义符号的可访问性为“公共”的。@readonly符号是只读的。@requires标注依赖项。@returns|@return函数的返回值。@static某个符号是静态成员。@throws函数会抛出的错误。@todo列出待完成的任务。@type符号的数据类型。@typedef自定义类型。@version符号的版本。