JavaScript多行注释中的“ @”符号有什么作用？ [英] What does the '@' symbol do in JavaScript multiline comments?

问题描述

在我浏览Muuri源代码并到处都看到它之后，真的很好奇：

Just really curious after I was poking around the Muuri source code and saw this everywhere:

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中的代码，它们会被突出显示好像他们不是评论。

@param and @returns don't seem to actually do anything (I think), but they ARE highlighted differently. In fact, if you look at the code in git they're highlighted as though they're not comments.

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

Is this some JavaScript syntax I'm unaware of? What's going on here? I would love to know.

推荐答案

这只是在使用 JSDoc评论。语法受Java影响，该Java将JavaDoc注释作为标准的一部分。简而言之，该注释记录了函数或方法的功能，并且语法略有特殊-这是一个以 / ** 开头的块注释，而不仅仅是 / * 可以将其与普通的块注释区分开来，您可以使用一些注释来表示不同的含义：

This is just utilisting JSDoc comments. The syntax is influenced by Java which has JavaDoc comments as part of the standard. In short, the comment is documenting what a function or method does and it has slightly special syntax - it is a block comment that starts with /** instead of merely /* to differentiate it from a normal block comment and you can use some annotations to denote different meanings:

• @param 表示这是一个参数。
  
  
  
  
  • {} 中的值表示参数的类型-在这种情况下为 * 的意思是任何，但是您要记录类似 @param {string} 或 @param {number }
  
  
  • val 是函数使用的参数的名称。
  
  
  • 您可以选择为参数添加说明，例如 @param {*} val-用于foo和bar
  
  
  • @param means this is a parameter.
    • The value inside {} denotes the type of the parameter - in this case * means "any", but you to document something like @param {string} or @param {number}
    • the val is the name of the parameter that the function uses.
    • you can optionally add a description for the parameter e.g., something like @param {*} val - used for foo and bar
    
    
    • {} 内的值再次是类型。在这种情况下，为布尔值。
    
    
    • 您仍然可以选择为返回值添加注释，例如： @returns {Boolean}如果正确，则为true；如果错误，则为false
    
    
    • the value inside {} is the type again. In this case, a boolean.
    • you can still optionally add a comment for the return value, for example: @returns {Boolean} true if correct, false if incorrect

    您可以使用JSDoc语法记录更多内容，例如 @copyright 指定许可证，或 @throws 声明某些代码可能引发的预期异常。某些语法专用于函数或方法，其他语法专用于对象或整个文件。

    There are more things you can document using JSDoc syntax, like @copyright to specify a license or @throws to declare what are the expected exceptions that some code can throw. Some syntax is specific for functions or methods, other for objects or even whole files.

    总而言之，这是对文件中剩余描述的标准化。您不需要对注释做任何事情，但是您也可以使用读取注释并对其执行操作的工具，例如 Tern.js 将阅读注释并尝试检查您的代码是否符合要求，例如，您是否有

    All in all, it's an attempt to standardise the descriptions left in files. You don't need to do anything with the comment but you can also use tools that read the comments and act on them - some like Tern.js will read the comments and try to check if your code conforms, e.g., if you have

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

    ，然后调用 foo（ abc），则该工具可能会警告您应该传递数字。或者，如果您执行 foo（123）.replace（ a， b），则会收到警告，提示您尝试在应使用的字符串方法上使用

    and you call foo("abc") then you might get a warning by the tool that you should be passing a number. Or if you do foo(123).replace("a", "b") you can get a warning that you're trying to use string methods on what should be a boolean.

    其他工具可能只是抓取JS文件并生成文档。 Java使用JavaDoc做到这一点-您可以基于JavaDoc注释自动为您的方法和类生成文档。您将获得官方Java风格的文档 ，这意味着任何文档都将保持一致。

    Other tools might instead just crawl your JS files and generate documentation. Java does this with JavaDoc - you can generate the documentation for your methods and classes automatically basing it on the JavaDoc comments. You would get a documentation in the official Java style which means any documentation will be consistent.

    这篇关于JavaScript多行注释中的“ @”符号有什么作用？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！