JavaScript 注释规范

总原则

1. **如无必要，勿增注释。**如果代码本身很清晰，就没必要增加注释。
2. **一目了然，容易看懂。**合理的注释、空行等排版，可以给代码增加美感。

JSDOC 注释规范

概览及基础

• 注释标签规范来自 http://code.google.com/p/jsdoc-toolkit/w/list，具体使用可以先到这里查阅。
• @example 中牵涉到 DOM 标签需要使用转义字符。
• 使用 @since 标签标注是从哪一版本新加入的。
• 使用 @depracated 标注废弃的方法或属性。
• 在每个文件的最上面使用 @fileoverview, @author 等说明文件信息。

方法和属性

• 属性注释中必须写有 @type。例如： @type number 这是属性描述。

• 方法注释中必须使用 @param 把各参数描述详细，如果有返回值要使用 @return 描述清楚。 使用示例：

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

• 如果组件中有暴露给组件开发者的接口，不需要出现在文档中时，可使用 @ignore 屏蔽。

• 对于组件中的私有方法，使用 @private 标注。

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

  @param {Boolean} [name]
  

可使用的标签

@augments - Indicate this class uses another class as its “base.”
@author - Indicate the author of the code being documented.
@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.

祝使用愉快！