JavaScript 注释规范

JSDOC注释是指写在形如/** */的注释形式中的注释。

一、概览及基础

• 各种注释标签的书写规范来自http://code.google.com/p/jsdoc-toolkit/w/list，关于具体标签的使用不懂的问题可以先到这里查阅。
• @example中牵涉到DOM元素的需要使用转义字符，可以使用wordpress自带的可视编辑器编辑生成。
• 使用@since标签标注从哪一版本新加入的方法或属性。
• 使用@depracated标注废弃的方法或属性。
• 在每个文件的最上面使用@fileoverview @author等说明文件的信息。

二、顶层命名空间

• 如果是静态的变量，使用@namespace标注，如arale.config。
• 如果是函数，则使用@class标注，如arale.node。对于class标注的对象，使用 @param @return @example等来表述其构造函数及示例。
• 对于不常规的写法，比如arale.modual(“a.b.c”)，arale.declare(“a.b.c”)，在 @namespace 或 @class 之前使用@name a.b.c这种形式来标注真实的命名。
• 在全局顶部需要声明@author内容。如果是构造函数，则必须声明@example。

三、方法和属性

• 对于按照最原始不使用任何封装、便捷书写方法的代码，注释很容易书写，不需要任何注释书写技巧，可以直接跳到4开始浏览。例如：

  var a = function() {};
  a.prototype.func1 = function() {};
  a.b = 1;
  

  此类简单的写法不需要下面2、3亮点。但是对于使用：

  arale.declare(‘a.b.c’, ...)
  arale.module(‘a.b.c’, ...)
  

  等使用了封装后的便捷函数需要使用2、3两点技巧。

• 对于静态方法，使用@lends a.b.c使下方的方法和属性纳入其下。

• 对于实例方法，使用@lends a.b.c.prototype使下方的方法和属性纳入其下。

• 方法或属性的注释中第一行必须是描述信息，@description统一省略不写，直接写内容。

• 属性注释中必须写有@type使用方法：@type number 这是属性描述。

• 方法注释中必须使用@param把各参数描述详细，如果有返回值要使用@return描述清楚。对于每一个方法请尽可能使用@example添加使用示例，而且示例越多越好。 @param的使用示例：

  @param {string} s 这是参数描述 最简单的情况
  @param {string | number} abc  这是参数描述  //参数的类型多于一种
  @param {number} [abc] 这是参数描述 //可选参数
  @param {function(string, number): number} pa 这是描述 //参数是一个函数
  @param {string} [pa='abc'] 这是描述 //参数可选，默认值'abc'
  

• 对于组件中initbindpostCreate等暴露给组件开发者的接口不需要出现在文档中，使用@ignore屏蔽。

• 对于组件中的私有方法（用下划线开头），使用@private屏蔽。

• 对于方法中的可选参数，使用中括号将变量名称包括即可，例如

  @param {Boolean} [name]
  

四、可以使用的标签：

@augments - Indicate this class uses another class as its “base.”
@author - Indicate the author of the code being documented.
@argument - Deprecated synonym for @param.
@borrows that as this - Document that class's member as if it were a member of this class.
@class - Provide a description of the class (versus the constructor).
@constant - Indicate that a variable's value is a constant.
@constructor - Identify a function is a constructor.
@constructs - Identicate that a lent function will be used as a constructor.
@default - Describe the default value of a variable.
@deprecated - Indicate use of a variable is no longer supported.
@description - Provide a description (synonym for an untagged first-line).
@event - Describe an event handled by a class.
@example - Provide a small code example, illustrating usage.
@extends - Synonym for @augments.
@field - Indicate that the variable refers to a non-function.
@fileOverview - Provides information about the entire file.
@function - Indicate that the variable refers to a function.
@ignore - Indicate JsDoc Toolkit should ignore the variable.
@inner - Indicate that the variable refers to an inner function (and so is also @private).
@lends - Document that all an object literal's members are members of a given class.
@memberOf - Document that this variable refers to a member of a given class.
@name - Force JsDoc Toolkit to ignore the surrounding code and use the given variable name instead.
@namespace - Document an object literal is being used as a “namespace.”
@param - Describe a function's parameter.
@private - Indicate a variable is private (use the -p command line option to include these).
@property - Document a property of a class from within the constructor's doclet.
@public - Indicate an inner variable is public.
@requires - Describe a required resource.
@returns - Describe the return value of a function.
@see - Describe a related resource.
@since - Indicate that a feature has only been available on and after a certain version number.
@static - Indicate that accessing the variable does not require instantiation of its parent.
@throws - Describe the exception that a function might throw.
@type - Describe the expected type of a variable's value or the value returned by a function.
@version - Indicate the release version of this code.

五、代码示例

请参考/trunk/js/common/arale/base/resources/base.js

六、JSDOC MAVEN插件：

JSDOC插件中有两个命令：

1. mvn jsdoc:generate。generate这个goal的作用是生成文档。可以在任何一个ARALE JS项目中执行它，执行结果是在target下生成一个目录docs，在这一目录里有生成的文档。
2. mvn jsdoc:deploy。deploy这个goal的作用是将生成的文档上传到服务器上。

通过使用JSDOC MAVEN插件，可以很方便的生成ARALE框架本身的文档，产品线的代码如果注释写的好，同样可以通过插件生成良好的产品技术文档（或者产品API文档）。祝使用愉快！