ourai/js_comment_spec.md

## js_comment_spec.md

      
    Raw
  

              js_comment_spec.md
            
          
    JavaScript 注释规范

该规范说明了书写 JavaScript 注释的一些约定。
需要注释的位置


方法/函数前

注释说明

注释的格式

本规范中的注释格式主要是基于 YUIDoc Syntax 进行了一些扩展。
/**
 * method's description
 * 
 * @private(symbol of private method)
 * @method   method's name
 * @param    param_1's name {param_1's type}     param_1's description
 * @param    param_2's name {param_2's type}     param_2's description
 * @param    param_*'s name {param_*'s type}     param_*'s description
 * @return   {return value's type}   return value's description
 */


@private

@private

只有定义私有的方法/函数时才写此关键字

@method

@method    name


@param

@param    name {type}  description


name为unspecified时，代表该方法可传入不定数的参数
type为Variant时，代表该参数为任意类型

Type List

变量类型采用较 JavaScript 原生对象更为具体的方式

Object - 普通（或未特殊注明的）对象
Function - 函数
Array - 数组
JSON - JavaScript Object Notation
Node - HTML/XML DOM node
NodeList - HTML/XML DOM node list
jQuery - jQuery 对象
String - 字符串
Integer - 整型数字
Float - 浮点型数字
Number - 数字型字符串、整形数字或浮点型数字
RegExp - 正则表达式


@return

@return    {type} description


@return关键字必须写
若无返回值时则省略type和description