软件并不只是包括可以在计算机上运行的电脑程序,与这些电脑程序相关的文档,一般也被认为是软件的一部分。简单的说软件就是程序加文档的集合体。

随着项目的升级进化,前端产生的 JavaScript 代码越来越多越复杂;同时,也有越来越多的 JavaScript 问题出现,其中 JavaScript 文档的编写和维护成为一个亟待解决的难题。

许多现代编程语言都有自己的集成化文档生成工具,像 Java 有 JavaDoc ,.NET 有 NDoc,PHP 有 PHPDoc,这些自动化文档工具可以根据代码中的注释自动生成代码文档。本文将介绍的 JSDoc 也是这样的工具。

简介

JSDoc 3 是 JsDoc Toolkit 的升级版本,JsDoc Toolkit 是一个自动化文档工具,它是发布在 Google code 上的一个开源项目,和其他语言的文档工具一样,它可以自动从 JavaScript 代码中提取注释生成格式化文档。从 2010年7月27日 开始,JsDoc Toolkit 2 已经停止开发了,因此如果要使用 JSDoc 的话,还是推荐采用 JSDoc 3。现在 JSDoc 3 代码托管在 GitHub 上,项目地址:https://github.com/jsdoc3/jsdoc

安装

JSDoc 3 在本地安装依赖于 Nodejs,因此首先需要下载 Nodejs 进行安装:

http://nodejs.org/
http://nodejs.org/dist/v0.10.25/x64/node-v0.10.25-x64.msi

安装完后,使用以下命令安装 JSDoc 3 即可(:必须使用超级管理员身份安装):

# stable
npm install jsdoc@"<=3.3.0" -g
# dev
npm install git+https://github.com/jsdoc3/jsdoc.git -g

# test
C:\Users\moodpo>jsdoc --help
JSDoc 3.3.0-alpha3 (Wed, 25 Dec 2013 17:07:35 GMT)
......

使用

JSDoc 3 生成 API 文档完全依赖于你的代码注释,因此了解 JSDoc 3 的注释规则是最重要的。首先,注释必须要以 /** 开头,如果使用 /* 将不被识别;其次,每个注释块都应该包含唯一的主标签,和零个或多个副标签。

1. JSDoc 3 标签规范

标签 描述
@abstract/@virtual This member must be implemented (or overridden) by the inheritor.
@access Specify the access level of this member - private, public, or protected.
@alias Treat a member as if it had a different name.
@augments/@extends 标明一个函数继承另一个函数,如 A 继承 B 则可以在 A 的注释中加 `@augments B`
@author Identify the author of an item.
@borrows 参考,如 A 和 B 两个函数意义相同,则可以在 B 的注释中加 `@borrows A as B`,而不需重复添加注释
@callback/@typedef 标明此方法是一个回调函数
@classdesc 对一个类的描述
@constant/@const 常量标识
@constructor/@class 标明是构造器函数,可使用 `new` 关键字实例化
@constructs 当使用对象字面量形式定义类时,可使用此标签标明其构造函数
@copyright 描述版权信息
@default 默认值
@deprecated 弃用
@desc/@description 如果在注释开始描述可省略此标签
@enum 一个类中属性的类型相同时,使用此标签标明
@event 标明一个可触发的事件函数,一个典型的事件是由对象定义的一组属性来表示。
@example 示例,代码可自动高亮
@exports 标识此对象将会被导出到外部调用
@external/@host 标识此类、命名空间或模块来自外部
@file 描述文件功能
@fires/@emits 标明当一个方法被调用时将出发一个特殊类型的事件
@global 全局变量标识
@ignore 忽略此注释块
@inner 标明此代码是父类的内部变量
@instance 标明此代码是父类的实例
@kind 标明代码在其文档中的类型,如Class、Modual等
@license 采用的开源协议版本
@link 内联标签,创建一个链接,如 `{@link http://github.com Github}`
@member/@var 记录一个基本数据类型的成员变量
@memberof 指定一个变量所属的父类
@method/@function/@func 标记一个方法或函数
@mixes 标记一个对象混合了另一个对象的所有成员
@mixin 一个 `mixin` 提供了旨在将方法添加到对象上的功能
@module 标明当前文件模块,在这个文件中的所有成员将被默认为属于此模块,除非另外标明
@name 指定一段代码的名称,强制 JSDoc 使用此名称,而不是代码里的名称
@namespace 指定一个变量为命名空间变量
@param 标记方法参数及参数类型
@private/@protected/@public 标明变量访问等级
@property 标明一个对象的属性
@readonly 只读
@requires 标明运行代码所需模块
@returns/@return 标明返回值、类型及描述
@see 链接到一个参考位置
@since 描述此功能来自哪一版本
@static 描述一个不需实例即可使用的变量
@summary 对描述信息的短的概述
@this 说明 `this` 关键字所代表的意义
@throws 描述方法将会出现的错误和异常
@todo 描述函数的功能或任务
@tutorial 插入一个指向向导教程的链接
@type 描述代码变量的类型
@version 版本信息

更多内容请查看官方文档

2. 使用 conf.json 文件

安装完 JSDoc 3 后默认使用的配置文件为 conf.json.EXAMPLE,内容如下:

{
    "tags": {
        "allowUnknownTags": true
    },
    "source": {
        "includePattern": ".+\\.js(doc)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "plugins": [],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

我们可以定义自己的 conf.json 文件,使用此文件可以指定 JSDoc 输出目录、命令行操作参数、使用的插件、输出模版以及读取的文件等,以下是完整的文件内容:

// 使用时请删除所有注释
{
    "tags": {
        "allowUnknownTags": true //允许输出位置标签
    },
    "source": { // 指定读取的源文件
        "include": [], // 包含文件列表
        "exclude": [], // 不包含文件列表
        "includePattern": ".+\\.js(doc)?$", // 正则方式
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "plugins": [], // 启用插件列表,可在 JSDoc 目录下找到所有的插件
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    },
    "opts": { // 命令行操作参数配置,详细内容请查看 http://usejsdoc.org/about-commandline.html
        "template": "templates/default",  // same as -t templates/default
        "encoding": "utf8",               // same as -e utf8
        "destination": "./out/",          // same as -d ./out/
        "recurse": true,                  // same as -r
        "tutorials": "path/to/tutorials", // same as -u path/to/tutorials, default "" (no tutorials)
        "query": "value",                 // same as -q value, default "" (no query)
        "private": true,                  // same as -p
        "lenient": true,                  // same as -l
        // these can also be included, though you probably wouldn't bother
        // putting these in conf.json rather than the command line as they cause
        // JSDoc not to produce documentation. 
        "version": true,                  // same as --version or -v
        "explain": true,                  // same as -X
        "test": true,                     // same as -T
        "help": true,                     // same as --help or -h
        "verbose": true,                  // same as --verbose, only relevant to tests.
        "match": "value",                 // same as --match value, only relevant to tests.
        "nocolor": true                   // same as --nocolor, only relevant to tests
    }
}