Course contentsShow
← JavaScript
Lesson 2612 of 2,72353. Type Safety Without TypeScriptFree lesson

Documenting Return Values with @returns

Annotate function return types with @returns to clarify what a function produces.

Documenting Return Values with @returns

You'll learn how to use the @returns tag in JSDoc comments to clearly document what a function gives back to its caller.

What Is @returns?

Just as @param tells readers what goes into a function, the @returns tag (or its alias @return) documents what comes out. It specifies the type and meaning of the value a function produces, making your code self-documenting and enabling better IDE autocomplete and type checking.

Think of @returns as the "receipt" for your function—it tells you exactly what you're getting back after the function does its work.

How to Use @returns

The basic syntax is:

/**
 * Calculates the area of a rectangle.
 * @param {number} width - The width of the rectangle
 * @param {number} height - The height of the rectangle
 * @returns {number} The calculated area
 */
function calculateArea(width, height) {
  return width * height;
}

You can also document functions that return objects or more complex types:

/**
 * Fetches user data by ID.
 * @param {string} userId - The user's unique identifier
 * @returns {{name: string, email: string}} The user object
 */
function getUser(userId) {
  return { name: "Alice", email: "alice@example.com" };
}

For functions that don't return meaningful values, you can use @returns {void} or simply omit the tag.

Why It Matters

Adding @returns makes your functions' contracts explicit. Other developers (including future you) instantly understand what to expect without reading the implementation. Modern editors use these annotations to provide better IntelliSense and catch type mismatches.

Key Takeaway: Use @returns to document the type and purpose of what your function produces, creating clearer contracts and enabling better tooling support.