# Jsdoc Writer

> Add JSDoc comments to JavaScript or TypeScript functions that are missing documentation. Use when asked to document functions, add JSDoc, or improve code comments.

- Skill: `davila7/jsdoc-writer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add davila7/jsdoc-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/davila7/jsdoc-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: davila7 (https://skillmd.com/u/davila7)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/davila7/jsdoc-writer

---


## Instructions

Identify the functions or methods that are missing JSDoc comments. If the user specified a file, focus on that file. Otherwise, focus on whatever code is currently being discussed.

For each undocumented function, write a JSDoc block following these rules:

### Content rules

1. Read the function signature to determine parameter names and infer types from usage context, TypeScript annotations, or surrounding code.

2. Write a concise `@description` (one line maximum) that explains what the function does. If the function name already makes this completely obvious (`isAuthenticated`, `formatDate`), skip the description line and let the `@param` and `@returns` tags carry the documentation.

3. Write one `@param` tag per parameter:
   - Include the type in curly braces: `@param {string} name`
   - Add a short description after the parameter name
   - Mark optional parameters with a `?` suffix or bracket notation: `@param {string} [name]`

4. Write `@returns` with the return type and a brief description of what is returned and under what conditions. If the function returns void or never returns a meaningful value, omit `@returns`.

5. Write `@throws` if the function throws an exception under documented conditions: `@throws {TypeError} If name is not a string`.

6. Do not add `@author`, `@date`, `@version`, or other lifecycle metadata — these are noisy and go stale quickly.

### Style rules

- Explain the **why** only when the behavior would surprise a reader who knows JavaScript and the domain. Do not describe what the code does — the code already shows that.
- Keep descriptions short. If a description needs more than one sentence, the function probably does too much.
- Use the existing codebase's type vocabulary. If the codebase calls something a `UserId`, use `UserId`, not `string`.

### Output format

Print the function name as a heading, then the completed JSDoc block. If the function already has a JSDoc block that is incomplete, print the corrected version.

Example output format:

```
getUserById

/**
 * Fetches a user record by its unique identifier.
 * Returns null if no user with that ID exists.
 *
 * @param {string} id - The user's unique identifier.
 * @returns {Promise<User | null>} The user record, or null if not found.
 * @throws {DatabaseError} If the database connection fails.
 */
```