JSDoc @deprecated for Legacy Functions

Documenting Deprecated Functions

The @deprecated tag warns developers that a function should no longer be used and directs them to the replacement. IDEs display deprecation warnings and strikethrough formatting.

Example Signature

function getUser(id: number): User

Generated JSDoc

/**
 * Retrieves a user by their numeric ID.
 *
 * @deprecated Since v3.0.0. Use {@link getUserById} with a UUID string
 *   instead. Numeric IDs will be removed in v4.0.0.
 *
 * @param {number} id - The legacy numeric user ID.
 * @returns {User} The user object.
 * @throws {NotFoundError} If no user has this numeric ID.
 *
 * @example
 * ```typescript
 * // Old (deprecated):
 * const user = getUser(42);
 *
 * // New (recommended):
 * const user = getUserById("uuid-abc-123");
 * ```
 *
 * @see {@link getUserById} for the replacement API.
 * @since 1.0.0
 */

@deprecated Best Practices

1. State when it was deprecated: "Since v3.0.0"
2. Name the replacement: Use {@link} to reference the new function
3. Give a removal timeline: "Will be removed in v4.0.0"
4. Show migration example: Before/after code in @example
5. Use @see: Link to the replacement and migration guide

IDE Integration

Most modern IDEs recognize @deprecated and will:

• Show strikethrough on usages
• Display a warning on hover
• Suggest the replacement in quick-fix menus

TSDoc @deprecated

TSDoc supports the same @deprecated tag. The message after the tag is rendered as the deprecation reason:

/**
 * @deprecated Use `getUserById` instead. This will be removed in v4.0.
 */