摘要：包含描述與指定所有參數和返回值的類型和值的注釋標簽。返回值的類型和描述或者更多示例更多請參考以下網站為本文參考，歡迎留言糾正。注解注釋原文代碼注釋規范與示例注釋

做為一個有情懷的Coder，最近收集了一下JavaScript代碼注釋范例，希望能夠幫助大家擼得一手妖媚而又放蕩的Bug。

使用 // 作為單行注釋。

單行注釋符后與注釋內容保留一個空格。

//bad comments
// good comments

單行注釋需要在說明的代碼之上另起一行，并且在注釋前插入空行。

function isType(content, expect) {

    // good
    // Using Object.prototype.toString to judge data types.
    let type = Object.prototype.toString.call(content).replace(/[objects|]/g, "");

    return type === expect;
}
// bad
console.log(isType("hello", "String"));       // return true

帶有 // FIXME: 或 // TODO: 的前綴的注釋可以幫助其他開發者快速了解這是一個需要復查的問題，或是給需要實現的功能提供一個解決方式。這將有別于常見的注釋，因為它們是可操作的。使用 FIXME -- need to figure this out 或者 TODO -- need to implement。

使用 // FIXME: 標注問題。

class Calculator {
    constructor() {
        // FIXME: shouldn"t use a global here
        total = 0;
    }
}

使用 // TODO: 標注問題的解決方式。

// Support: IE, Opera, Webkit
// TODO: identify versions
// getElementById can match elements by name instead of ID
if ( newContext && (elem = newContext.getElementById( m )) &&
    contains( context, elem ) &&
    elem.id === m ) {

    results.push( elem );
    return results;
}

多行注釋星號 * 對齊，并且注釋內容不要寫在起始符號 /**與結束符號 */ 所在行。

// bad
/* matches from matchExpr["CHILD"]
  1 type (only|nth|...)
   2 what (child|of-type)
*/

// good
/* 
    matches from matchExpr["CHILD"]
    1 type (only|nth|...)
    2 what (child|of-type)
 */

使用 /* ... */ 作為文件注釋。

文件注釋主要包含：概要介紹、版本信息、版權聲明、開源協議、修改時間等說明內容。

React.js

/** @license React v16.4.0
 * react.development.js
 *
 * Copyright (c) 2013-present, Facebook, Inc.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */

jQuery.js

/*!
 * jQuery JavaScript Library v3.3.1
 * https://jquery.com/
 *
 * Includes Sizzle.js
 * https://sizzlejs.com/
 *
 * Copyright JS Foundation and other contributors
 * Released under the MIT license
 * https://jquery.org/license
 *
 * Date: 2018-01-20T17:24Z
 */

開源項目的開發版本與生產版本中都會保留文件注釋，且必須對引用的其他開源代碼進行說明。

使用 /** ... */ 作為文檔API注釋。包含描述與指定所有參數和返回值的類型和值的注釋標簽。

/**
 * Maps children that are typically specified as `props.children`.
 *
 * See https://reactjs.org/docs/react-api.html#react.children.map
 *
 * The provided mapFunction(child, key, index) will be called for each
 * leaf child.
 *
 * @param {?*} children Children tree container.
 * @param {function(*, int)} func The map function.
 * @param {*} context Context for mapFunction.
 * @return {object} Object containing the ordered map of results.
 */
function mapChildren(children, func, context) {

  if (children == null) {
    return children;
  }

  var result = [];
  mapIntoWithKeyPrefixInternal(children, result, null, func, context);

  return result;
}

@param 指定參數的名稱。您還可以包含參數的數據類型，使用大括號括起來，和參數的描述。

/**
 * @param content
 */

注釋變量名 和 變量類型

/**
 * @param {String} type
 */

注釋變量名、變量類型 和 變量說明

/**
 * @param {String} attrs Pipe-separated list of attributes
 */

連字符可以使注釋閱讀友好

參數變量名與參數說明之間使用連字符 -

/**
 * @param {object} partialState - Next partial state to be merged with state.
 */

對象參數屬性描述

描述一個對象參數的屬性

/**
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee"s department.
 */

同樣，可以聯想到如果假如 employee 參數是一個數組，這個數組中包含 name 和 department 元素，那么可以這么描述。

描述參數的屬性值在數組中

/**
 * Assign the project to a list of employees.
 * @param {Object[]} employees - The employees who are responsible for the project.
 * @param {string} employees[].name - The name of an employee.
 * @param {string} employees[].department - The employee"s department.
 */

可選參數和默認值

JSDoc可選參數

/**
 * @param {string} key - Key to be escaped.
 */

JSDoc可選參數和默認值

/**
 * @param {Number} [index=0] - Somebody"s name.
 */

Google Closure Compiler 可選參數

/**
 * @param {string=} somebody - Somebody"s name.
 */

多種類型參數

下面的例子演示了如何使用類型的表達式來表示一個參數可以接受多種類型（或任何類型），還有一個參數可以被多次使用。

/**
 * @param {(string|string[])} [somebody=John Doe] - Somebody"s name, or an array of names.
 */

允許任何類型

/**
 * @param {*} component - A component that could contain a manual key.
 */

可重復使用的參數

所有可變參數都是數字

/**
 * @param {...number} num - A positive or negative number.
 */

管道字符 | 用來連接聯合類型，聯合類型用來表明參數可以有多個類型

/** 
 * @param {string|null|undefined} str 
 */

因為參數是否非空很常見，因此有一個快捷方式用來標明聯合類型是否包含 null

/** 
 * @param {?string} str1 is a string or null 
 * @param {?string|undefined} str2 is a string, null, or undefined. The ? 
 *     prefix does not include undefined, so it must be included explicitly. 
 */

除了基本類型的所有類型，如Object,Array和HTMLDocument默認都可以為空，這些類型統稱為對象類型，因此 ? 前綴對對象類型是多余的

/** 
 * @param {Document} doc1 is a Document or null because object types are nullable by default. 
 * @param {?Document} doc2 is also a Document or null. 
 */

如果要聲明一個非空對象對開，可以用 ! 前綴

/** 
 * @param {!Array} array must be a non-null Array 
 * @param {!Array|undefined} maybeArray is an Array or undefined, but 
 *     cannot be null. 
 */

盡管一個方法中可以有任意多個可選參數，但是可選參數不應該出現在必須參數之前，如果出現在之前，代碼必須寫成如下形式

/** 
 * @param {string=} title Defaults to "New Spreadsheet". 
 * @param {string} author 
 */

大量的可靠參數，最好將其它移到一個必須的對象參數中

/**  
 * @param {{author: (string|undefined), title: (string|undefined), numRows: (number|undefined)  
 */

不定數量參數

Closure不定數量參數

/** 
 * @param {string} category 
 * @param {...} purchases 
 * @return {number} 
 */

注釋函數類型值的可選和可變參數

/** 
 * @param {function(string, string=)} ……
 * @param {function(string, ...[number]): number} ……
 */

回調函數

使用 @callback 標簽來定義回調類型，回調類型包含到 @param 中。

/**
 * This callback type is called `requestCallback` and is displayed as a global symbol.
 *
 * @callback requestCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */

/**
 * Does something asynchronously and executes the callback on completion.
 * @param {requestCallback} cb - The callback that handles the response.
 */

@return / @returns 返回值的類型和描述

/**
 * @return {object} Object containing the ordered map of results.
 * @return {!number} The number of children in this subtree.
 */

或者

/**
 * @returns {boolean} True if mounted, false otherwise.
 * @returns {Element|Object|Boolean} The input node if acceptable, otherwise a falsy value
 */

更多示例

/**
 * @param {?Function(*, Boolean)} callback - To invoke upon traversing each child.
 * @param {String|Number} ref
 * @param {?*} children - Children tree container.
 * @param {Element|Object=} context
 * @param {!ArrayLike} nodes
 * @returns {Element|Object|Boolean} The input node if acceptable, otherwise a falsy value
 */

/**
 * @param {?*} children - Children tree container.
 * @param {!string} nameSoFar - Name of the key path so far.
 * @param {!function} callback - Callback to invoke with each child found.
 * @return {!number} The number of children in this subtree.
 */

以下網站為本文參考，歡迎留言糾正。

YUIDoc Syntax Reference
@use JSDoc
Closure javascript注解
Airbnb JavaScript Style Guide() { - 注釋
原文Airbnb JavaScript Style Guide() {
js/javascript代碼注釋規范與示例
Js注釋