JSDoc & Docstrings

Option B is a complete, well-formed JSDoc comment. It includes:

• Summary line: "Converts a string to a URL-safe slug." — one sentence, imperative mood
• @param: type + name + description ("The input string to slugify")
• @returns: type + description ("The lowercased, hyphen-separated slug")
• @example: shows concrete input → output behavior

JSDoc style conventions:
• Use imperative mood for the summary: "Converts...", "Validates...", "Returns..." — not "This function converts..."
• Keep the summary to one sentence ending with a period
• Describe what the parameter IS, not what the code does with it
• @returns should describe the return value meaning, not just the type
• @example is optional but extremely valuable for non-obvious functions

Tools that parse JSDoc: VS Code IntelliSense, TypeDoc, JSDoc HTML generator.

@throws {ValidationError} When the email format is invalid.

The @throws tag format:
@throws {"{ErrorType}"} Description of when it throws.

Rules:
• The error type in curly braces: {"{TypeError}"}, {"{RangeError}"}, {"{Error}"}, or a custom error class
• The description starts with "When" or "If": "When the token has expired", "If the user does not exist"

Multiple @throws:

* @throws {ValidationError} When required fields are missing.
* @throws {AuthError} When the JWT signature is invalid.
* @throws {RateLimitError} When more than 100 requests per minute.

Why document throws:
• Callers need to know what exceptions to catch
• In TypeScript, exceptions are not part of the type system (unlike Java's checked exceptions)
• Without documentation, a caller may not wrap the call in try/catch and the error propagates silently to the top level

@param {"{number}"} [timeout=5000] — the JSDoc syntax for optional parameters with defaults:

• Square brackets around the name: [timeout] = optional
• Default value after equals: [timeout=5000] = optional, defaults to 5000
• Description should mention the unit: "milliseconds", "seconds", "bytes"
• Include "Defaults to X" in the description for clarity

JSDoc parameter documentation patterns:

@param {string} name               // required, no default
@param {string} [name]             // optional, no default (can be undefined)
@param {string} [name="anonymous"] // optional, defaults to "anonymous"
@param {Object} options            // required object
@param {string} options.host       // property of options
@param {number} [options.port=80]  // optional property with default

The options object pattern is particularly useful for functions with many configurable parameters.

@deprecated signals: "this still works, but don't use it in new code — migrate to the replacement".

Best practice — include WHY and WHAT to use instead:

/**
 * @deprecated Since v2.3.0. Use {@link fetchUserById} instead.
 * Will be removed in v3.0.0.
 */
function getUser(id: string) { ... }

Good @deprecated annotation includes:
1. Since version — when it was deprecated
2. Replacement — {"{@link newFunctionName}"} — creates a clickable link in IDEs
3. Removal version (if known) — when it will be removed

IDE behaviour: VS Code shows deprecated symbols with a strikethrough in autocomplete and usages. TypeScript compiler can issue warnings for deprecated usage with the @deprecated JSDoc tag even without strict mode.

Communication in English: "deprecated" ≠ "deleted". Deprecated = "we recommend you stop using this". Deleted = "this no longer exists".

@returns {"{Promise}"} — the correct way to document async functions in JSDoc:

• The type is {"{Promise}"} where T is the resolved value's type
• Describe BOTH the resolved value AND potential rejection causes

Examples:

@returns {Promise<void>} Resolves when the email is sent.
@returns {Promise<string>} Resolves with the generated token.
@returns {Promise<User[]>} Resolves with an array of matching users.
@returns {Promise<User|null>} Resolves with the user, or null if not found.

Also document rejections:

* @returns {Promise<User>} Resolves with the authenticated user.
* @throws {AuthError} If the token is expired or invalid.
* @throws {NetworkError} If the identity provider is unreachable.

Note: In TypeScript with strict mode, the return type annotation in the function signature is often sufficient. JSDoc is most valuable in .js files without TypeScript types, or for public API documentation.

Option C — "@throws {Error} when there is an error" is too vague to be useful:

Problems:
1. {"{Error}"} — the base Error class; should name the specific error type
2. "when there is an error" — circular; every @throws tag is about an error
3. No condition — what triggers the throw? What input? What state?

Improved version:
@throws {"{NotFoundError}"} When no user with the given ID exists in the database.
Or: @throws {"{TypeError}"} When userId is not a valid UUID string.

Evaluating options A, B, D:
• Option A ✓ — type + name + meaningful description
• Option B ✓ — type + both possible values explained ("true if… false otherwise")
• Option D ✓ — @example with realistic input and expected return

The standard for @throws: specific error type + specific triggering condition. If you can't write a specific condition, the function probably needs clearer error handling design.