JavaScript 多行注释中的“@”符号有啥作用？

Posted 2023-02-21

【中文标题】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 的参数。

【参考方案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，这意味着任何文档都是一致的。