What is the purpose of text preceded with @ in comments

Question

I've seen comments that contain @some text in it. This is an example from express.js:

/**
 * Create an express application.
 *
 * @return {Function}
 * @api public
 */ 

These @comments are also color coded differently by the Visual Studio Code.

What is the purpose of @ preceded comments?

Answer 1

These are JSDoc comments. They are useful for explaining what a function does, what parameters and types it takes, and what it outputs, when hovering or using a function in your IDE.

For example, in VSCode, this code: Will produce this tool-tip:

Answer 2

It's called JSDoc, and it's an auto-generated documentation (in the form of comments) that can be used in your JavaScript files.

It interacts with many IDEs (Integrated Development Interfaces), such as VSCode, and it's useful for showing type annotations as well. Here's a type-annotated function:

/**
 * Represents a person
 * @constructor
 * @param {string} name - The name of the person
 * @param {number} age - The age of the person
 */
function Person(name, age) {
    this.name = name;
    this.age = age;
}

As you can see, the JSDoc documentation goes above the function it's describing, and it knows that:

• The function represents a person
• The function is a constructor (@constructor)
• The function takes a parameter (@param) of type string, named name, which represents the name of the person
• The function takes a parameter (@param) of type number, named age, which represents the age of the person

In this sense it's kind of like TypeScript - it uses type annotations (except because they're just comments, it's not enforced like it would be by the TypeScript compiler).