JavaScript 多行注释中的“@”符号有什么作用？答案

【问题标题】：What does the '@' symbol do in JavaScript multiline comments?JavaScript 多行注释中的“@”符号有什么作用？
【发布时间】：2019-10-16 01:16:47
【问题描述】：

在我浏览了 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 中的代码，它们会突出显示 as though they're not comments。

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

【问题讨论】：

它们是 cmets，提供函数isNodeList 接受的参数和返回值的描述。您的函数返回 boolean value 并接受 * 指示的所有 DT 的参数。

标签： javascript syntax comments

【解决方案1】：

这只是使用JSDoc comments。语法受 Java 的影响，Java 将 JavaDoc cmets 作为标准的一部分。简而言之，注释记录了一个函数或方法的作用，它有一些特殊的语法——它是一个以/** 开头的块注释，而不是仅仅/*，以将它与普通块注释区分开来，你可以使用一些表示不同含义的注释：

@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 声明某些代码可能抛出的预期异常。一些语法是特定于函数或方法的，另一些是特定于对象甚至整个文件的。

总而言之，这是一种将文件中的描述标准化的尝试。您不需要需要对评论做任何事情，但您也可以使用读取 cmets 并对其采取行动的工具 - 有些像 Tern.js 将读取 cmets 并尝试检查您的代码是否符合，例如，如果你有

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

如果您致电foo("abc")，那么您可能会收到工具警告您应该传递一个数字。或者，如果您使用foo(123).replace("a", "b")，您可能会收到一条警告，提示您正在尝试对应该是布尔值的字符串方法。

其他工具可能只是抓取您的 JS 文件并生成文档。 Java 使用 JavaDoc 做到这一点 - 您可以基于 JavaDoc cmets 自动为您的方法和类生成文档。你会得到一个文档in the official Java style，这意味着任何文档都是一致的。

【讨论】：