JavaScript 注释规范

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