写API文档

很多人都觉得写文档是一件很枯燥而且吃力不讨好的事情，但实际情况并不是这样。我们可以通过代码注释自动生成文档，这样就不用再去专门写文档了。很多人觉得这是一个不错的点子，因为根据某些关键字和特定的格式自动生成可阅读的参考手册本身就是“某种编程”。

最早利用注释生成API文档的工具诞生自Java业界，这个工具名叫“javadoc”，和Java SDK（软件开发工具包）一起提供，但这个创意迅速被其他语言借鉴。JavaScript领域有两个非常优秀的开源工具，它们是JSDoc Toolkit（http://code.google.com/p/jsdoc-toolkit/）和YUIDoc（http://yuilibrary.com/projects/yuidoc）。

生成API文档的过程：

  • 以特定的格式来写代码
  • 运行工具来对代码和注释进行解析
  • 发布工具运行的结果，通常是HTML页面

这种语法包括十几种标签（tag），写法类似于：

  1. /**
  2.  * @tag value
  3.  */

比如这里有一个函数reverse()，可以对字符串进行反序操作。它的参数和返回值都是字符串。给它补充注释如下：

  1. /**
  2. * Reverse a string
  3. *
  4. * @param {String} input String to reverse
  5. * @return {String} The reversed string
  6. */
  7. var reverse = function (input) {
  8.     // ...
  9.     return output;
  10. };

如你所见，@param是用来说明输入参数的标签，@return是用来说明返回值的标签，文档生成工具最终会将这种带注释的源代码解析成HTML文档。

示例：YUIDoc

YUIDoc的初衷是为YUI（Yahoo! User Interface）库生成文档，但其实它也可以应用于任何项目。为了更充分的使用YUIDoc，你需要学习它的注释规范，比如模块和类的写法。（尽管在JavaScript中其实是没有类的概念的）。

让我们看一个用YUIDoc生成文档的完整例子。

图2-1展示了最终生成的文档的样子，你可以根据项目需要定制HTML模板，让生成的文档更加友好和个性化。

这里提供了在线的demo，请参照http://jspatterns.com/book/2/。

这个例子中所有的应用作为一个模块（myapp）放在一个文件里（app.js），后续的章节会更详细的介绍模块，现在只需知道可以用一个YUIDoc的标签来表示模块即可。

图2-1 YUIDoc生成的文档

YUIDoc生成的文档

app.js的开始部分：

  1. /**
  2.  * My JavaScript application
  3.  *
  4.  * @module myapp
  5.  */

然后定义了一个空对象作为模块的命名空间：

  1. var MYAPP = {};

紧接着定义了一个包含两个方法的对象math_stuff，这两个方法分别是sum()和multi()：

  1. /**
  2. * A math utility
  3. * @namespace MYAPP
  4. * @class math_stuff
  5. */
  6. MYAPP.math_stuff = {
  7.     /**
  8.     * Sums two numbers
  9.     *
  10.     * @method sum
  11.     * @param {Number} a First number
  12.     * @param {Number} b The second number
  13.     * @return {Number} The sum of the two inputs
  14.     */
  15.     sum: function (a, b) {
  16.         return a + b;
  17.     },
  19.     /**
  20.     * Multiplies two numbers
  21.     *
  22.     * @method multi
  23.     * @param {Number} a First number
  24.     * @param {Number} b The second number
  25.     * @return {Number} The two inputs multiplied
  26.     */
  27.     multi: function (a, b) {
  28.         return a * b;
  29.     }
  30. };

这样就完成了第一个“类”的定义，注意以下标签：

  • @namespace

    包含对象的全局引用

  • @class

    代表一个对象或构造函数（JavaScript中没有类）

  • @method

    定义对象的方法，并指定方法的名称

  • @param

    列出函数需要的参数，参数的类型放在一对花括号内，后面跟参数名和描述

  • @return

    和@param类似，用以描述方法的返回值，可以不带名字

我们来实现第二个“类”，使用一个构造函数，并给这个构造函数的原型添加一个方法，看看YUIDoc在面对不同的对象创建方式时是如何工作的：

  1. /**
  2. * Constructs Person objects
  3. * @class Person
  4. * @constructor
  5. * @namespace MYAPP
  6. * @param {String} first First name
  7. * @param {String} last Last name
  8. */
  9. MYAPP.Person = function (first, last) {
  10.     /**
  11.     * Name of the person
  12.     * @property first_name
  13.     * @type String
  14.     */
  15.     this.first_name = first;
  16.     /**
  17.     * Last (family) name of the person
  18.     * @property last_name
  19.     * @type String
  20.     */
  21.     this.last_name = last;
  22. };
  23. /**
  24. * Returns the name of the person object
  25. *
  26. * @method getName
  27. * @return {String} The name of the person
  28. */
  29. MYAPP.Person.prototype.getName = function () {
  30.     return this.first_name + ' ' + this.last_name;
  31. };

在图2-1中可以看到生成的文档中Person构造函数的生成结果，值得注意的部分是：

  • @constructor 说明这个“类”其实是一个构造函数
  • @prototype 和 @type 用来描述对象的属性

YUIDoc工具是与语言无关的，只解析注释块，而不是JavaScript代码。它的缺点是必须要在注释中指定属性、参数和方法的名字，比如，@property first_name。好处是一旦你熟练掌握YUIDoc，就可以用它对任何语言源码生成文档。