doc-ring v0.0.6

这是一个专门用于生成Javascript文档的工具。只要注释文档遵循“jsdoc3”规范，就可以生成一份漂亮的文档。

安装

$ npm install doc-ring

配置项

• tutorials {Array} 教程、指南的路径，一般是README.md的markdown文件
• src {Array} 源文件路径
• dist {string} 输出文档的目录

WIKI

• jsdoc3命名路径
• jsdoc3文档规范具体说明

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 符号的版本。