@param {type} [name=default] - desc — optional with default
@returns {type} desc — return value
@throws {ErrorType} When X happens — exception condition
@deprecated Since v2.0. Use {@link newFn} instead.
@example slugify("Hello") // "hello" — usage example
Summary line: imperative mood, one sentence, ends with period
1 / 6
Which JSDoc comment correctly documents this function?
function slugify(text: string): string (converts "Hello World" → "hello-world")
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.
2 / 6
A function can throw an error. Which @throws tag is correctly written?
@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
3 / 6
Which is the correct way to document an optional parameter with a default value in JSDoc?
@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.
4 / 6
What does the @deprecated tag communicate?
@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".
5 / 6
A function returns a Promise. Which @returns tag is correct?
@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.
6 / 6
You are reviewing a JSDoc comment. Which part is incorrectly written?
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.