六、JS 编写API文档

2018-06-17 19:10 更新

1. 生成API文档的步骤:

  • 编写特殊格式的代码块(即一些注释块)
  • 运行工具来解析代码和注释(工具如:JSDoc Toolkit和YUIDoc)
  • 发布工具解析的结果,大多数情况是采用HTML格式发布(如网页版的API文档就是利用工具生成的)

简单举例:

/**
* 翻转一个字符串
*
* @param  {String} 输入需要翻转的字符串
* @return {String} 翻转后的字符串
**/

var reverse = function (input) {
    //...
    return output;
};

YUIDoc范例:

完整范例:本程序由一个文件(app.js)组成,该文件仅有一个模块(myapp)。

app.js:

/**
* 我的javascript应用程序
*
* @module myapp
*/

//使用命名空间来定义一个空对象
var MYAPP = {};

//定义一个包含两个方法(sum()和multi())的math_stuff对象
/**
* @namespace MYAPP
* class math_stuff
*/

MYAPP.math_stuff = {
    /**
    * Sums two numbers
    *
    * @method sum
    * param     {Number}    是第一个数
    * param     {Number}    是第二个数
    * return    {Number}    两个输入的总和
    */
    sum: function (a, b) {
        return a + b;
    },
    /**
    * Multiplies two numbers
    * param     {Number}    是第一个数
    * param     {Number}    是第二个数
    * return    {Number}    两个输入相乘后结果
    */
    multi: function (a, b) {
        return a * b;
    }
};

@namespace:这里用于命名包含以上对象的全局引用的名称

@class:这里有些命名不当,他实际意思是指对象或者构造函数

@method:定义对象中的方法和方法名

@param:列举函数所使用的参数。其中将参数类型用大括号括起来,并在其后注释参数名及描述。

@return:类似于@param,这里用于描述返回值的,并且该方法没有名称。

@constructor:表明这个“类”实际上是一个构造函数

@property和@type描述了对象的属性。

2. 编写API目的:

  • 为API编写注释不仅仅是一中提供参考文档的简便方法,而且还有其他用途——通过再次审查代码,提高代码质量。
  • 在解决问题时写出的解决方案仅仅是一个初稿。该解决方案可以给出令人期待的输出,但是该方案是否是最佳方案呢?改代码是否可读、易于理解、维护和升级呢?当您再次审视代码时您将更加确定代码哪些部分可以改进——如何使得代码更容易继续更新,移除一些不足之处等。它可以极大地帮助您创建高质量的代码。


以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号

意见反馈
返回顶部