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中查看代码，它们将突出显示as though they're not comments。

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

Answer 1

这只是愚蠢的JSDoc comments。磁力线受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注释自动为您的方法和类生成文档。您将获得一个文档in the official Java style，这意味着所有文档都是一致的。

JavaScript多行注释中的'@'符号有什么作用？

1 个答案: