2014年1月

使用 JSDoc 3 自动生成 JavaScript API 文档

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

随着项目的升级进化,前端产生的 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
    }
}

就让这时光奔腾如流水

二零一三年已渐渐远去,在不知不觉中一四年的第一个月也快要逝去了。坦然者谓之:就让这时光奔腾如流水……而对于我来说,一三年却是一个不折不扣的曲折离奇,悲喜交加的一年,很多积压的事情在这一年爆发,很多逃避的事情在这一年不得不去面对了。

小年的时候我曾经发布过我的《2013年年终总结》,但是后来我把它删掉了,我觉得用工作、生活和展望,如一二年年终总结那样的形式已经无法描述我的二零一三了。我只想凭我对一三年的记忆去写,仅当是对过去那些日子的纪念吧。

大事记

  • 一月相识两年多后和豆豆完婚
  • 四月辞职并加入神州泰岳
  • 六月我的女儿盈珊出生
  • 九月善意的谎言破灭,隐瞒的事情人尽皆知
  • 十月搬家到帝都的一个小村公寓里,从此“过上”了朝九晚五的生活
  • 十月在广州出差,浴血奋战终奇迹完成任务
  • 十二月喜获公司企业文化奖之勇士奖

琐碎

  • 博客迁移到 Hostigation 的洛杉矶主机
  • 毕业三年后会母校拿毕业证 ^_^
  • 注册 GitHub 并开源了自己的第一个项目
  • 读完 《Struts 2 in Action》
  • 基于百姓网前端模版格式归纳总结出 IAM 3.0 产品的前端模版
  • 加入泰岳后开始专攻前端,并开始逐步积累自己的 CSS、JavaScript 知识
  • 读完 《JavaScript 语言精粹》
  • 发布两款 Typecho 皮肤:Moodpo、RedSexy
  • 博客经历了从 Typecho 0.8 -> Liquidluck -> Hexo -> Typecho 0.9 后趋于稳定
  • ......

感想

一三年经历了许许多多,最令我深刻的还是自翔的“超脱”,其实还不够超脱。这也难怪,有且只有我的家人或者说我爱的人能令我失控吧;最令我懊恼的是我一直以来懊恼的,没有“毅力”,不懂得坚持,这没什么好说的了,我不想再这样懊恼下去了;最令我苦闷的,当然还是豆豆和我妈两个人的结,似乎已变成一个死结,再也解不开一样,但我仍相信“世上没有解不开的结”这句话;最令我高兴的,哈,那当然是我的宝贝女儿盈珊的出生了,出生过程顺利,但后来有黄疸肺炎什么的,不过总算过来了,纳,以后当然一定快乐的成长吧!最令我难忘的要数广州之行,那一个个日夜将在我记忆里长存......

2014

人生不过两万天,过去一年我又离那个三更近了许多。想想现在,想想自己,再想想未来,些许后怕。是时候去做自己喜欢的事情了,是时候为自己做一些事情了。

人生短暂不只因时间短暂,而是因人事纷繁!

随便记录下吧先:

  • 坚持每周两篇博文
  • 完成 d.moodpo.com
  • 继续学习 JavaScript,读完《JavaScript 权威指南》等书
  • 回归霸气...
  • 工作继续...

2014-02-08 12 59 22.png