What does the '@' symbol do in JavaScript multiline comments?

Question

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 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.

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

Answer 1

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 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
• the @return documents the return of the function.
  • 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

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.

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) {}

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.

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.