这是一个专门用于生成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方式定义一个模块。
/** * 一些描述 * @module foobar * @property */
构建和部署
回到“gulpfile.js”文件,书写如下代码:
var docRing = ;var gulp = ; gulp;
我们将输出文档定义在hello-doc目录下的“build”中。
现在在命令行中运行gulp
即可输出文档:
$ gulp
现在根目录下应该会出现一个“build”目录,然后可以将它复制到apache服务器中运行,或将“build”目录建成一个静态文件服务器即可查看文档。
首页和教程文档
API文档有一个默认首页,用户也可以添加自定义首页。首页中可以放置对API库的综述等内容。
自定义的首页必须是一个markdown文件,只要将此文件路径包含在src
配置项中即可。
教程(tutorials)是针对一些特定主题的文档,例如angular的tutorial文档,教程可以有多个,每个教程文档必须是markdown格式的文件,有专门的tutorials
配置项用于指定教程文件。
支持的标签
@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
符号的版本。