JavaScript 多行注釋中的“@”符號有什么作用？

Question

在我瀏覽 Muuri 源代碼並隨處可見后，我真的很好奇：

var htmlCollectionType = '[object HTMLCollection]';
var nodeListType = '[object NodeList]';

/**
 * Check if a value is a node list
 *
 * @param {*} val
 * @returns {Boolean}
 */
export default function isNodeList(val) {
  var type = Object.prototype.toString.call(val);
  return type === htmlCollectionType || type === nodeListType;
}

@param 和 @returns 似乎實際上並沒有做任何事情（我認為），但它們的突出顯示方式不同。 事實上，如果您查看 git 中的代碼，它們會被突出顯示，就好像它們不是 comments 一樣。

這是我不知道的一些 JavaScript 語法嗎？ 這里發生了什么？ 我會很高興知道。

Answer 1

這只是利用JSDoc 注釋。 語法受 Java 的影響，Java 將 JavaDoc 注釋作為標准的一部分。 簡而言之，注釋記錄了一個函數或方法的作用，它有一些特殊的語法——它是一個以/**開頭的塊注釋，而不僅僅是/*以將其與普通塊注釋區分開來，您可以使用一些注釋表示不同的意思：

• @param表示這是一個參數。
  • {}的值表示參數的類型 - 在本例中*表示“任何”，但您需要記錄諸如@param {string}或@param {number}
  • val是函數使用的參數的名稱。
  • 您可以選擇為參數添加描述，例如@param {*} val - used for foo and bar
• @return記錄函數的返回。
  • {}的值又是類型。 在這種情況下，一個布爾值。
  • 您仍然可以選擇為返回值添加注釋，例如： @returns {Boolean} true if correct, false if incorrect

還有更多的東西，你可以使用JSDoc語法，如文檔@copyright指定許可證或@throws申報什么是預期的例外是一些代碼可以拋出。 有些語法是專門針對函數或方法的，有些則是針對對象甚至整個文件的。

總而言之，這是對文件中留下的描述進行標准化的嘗試。 你不需要對評論做任何事情，但你也可以使用閱讀評論並對其采取行動的工具 - 有些像Tern.js會閱讀評論並嘗試檢查你的代碼是否符合，例如，如果你有

/**
 * @param {number} bar
 * @return {boolean}
 */
function foo(bar) {}

並且您調用foo("abc")然后您可能會收到該工具的警告，提示您應該傳遞一個數字。 或者，如果您執行foo(123).replace("a", "b")您會收到警告，提示您嘗試對應該是布爾值的內容使用字符串方法。

其他工具可能只是抓取您的 JS 文件並生成文檔。 Java 使用 JavaDoc 做到這一點——您可以根據 JavaDoc 注釋自動為您的方法和類生成文檔。 您將獲得官方 Java 風格的文檔，這意味着任何文檔都將保持一致。