在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中查看代码，它们好像不是注释。

这是我不知道的JavaScript语法吗？这里发生了什么？我很想知道。

- yoursweater

---

它们是注释，提供有关 isNodeList 函数接受的参数和返回值的描述。您的函数返回布尔值，并接受所有 DT 参数，这些参数由 * 表示。 - random

Answer 1

这只是在使用JSDoc注释，它的语法受到Java的影响，Java有JavaDoc注释作为标准的一部分。简单来说，注释记录函数或方法的作用，并具有稍微特殊的语法 - 它是一个块注释，以/**开始，而不仅仅是/*，以区分它与普通块注释，并且您可以使用某些注释来表示不同的含义：

• @param 表示这是一个参数。
  • {}内的值表示参数的类型 - 在本例中，*表示"任何"，但您可以记录类似于@param {string}或@param {number}的内容。
  • val是函数使用的参数名称。
  • 您还可以为参数添加描述，例如：@param {*} val - 用于foo和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样式的文档（在这里），这意味着任何文档都将保持一致性。

- VLAZ

---

在某些工具中，@type 可以用于提供经过类型检查的 JavaScript。 - vhs