JSDoc for an Async Function with Promise Return
Generate JSDoc or TSDoc for async functions that return Promises. Covers documenting the resolved value type and @throws for rejected promises.
Detailed Explanation
Documenting Async Functions
Async functions always return a Promise. The JSDoc/TSDoc comment should document the resolved value type, not the Promise wrapper. It's also important to document potential rejection reasons using @throws.
Example Signature
async function fetchUser(id: string): Promise<User>
Generated JSDoc
/**
* Fetches a user by their unique identifier from the API.
*
* @param {string} id - The unique user identifier (UUID format).
* @returns {Promise<User>} The user object if found.
* @throws {NotFoundError} If no user exists with the given ID.
* @throws {NetworkError} If the API request fails.
*
* @example
* ```typescript
* const user = await fetchUser("abc-123");
* console.log(user.name);
* ```
*/
Documenting Promise Rejections
Async functions can reject in multiple ways. Each rejection reason should have its own @throws tag:
@throws {TypeError}— for invalid arguments@throws {NetworkError}— for connectivity issues@throws {NotFoundError}— for missing resources
Async vs Sync Documentation
The main difference is the return type. For async functions, always include Promise<T> in the @returns type annotation. The resolved value description should explain what the Promise resolves to, not that it returns a Promise.
TSDoc Style
In TSDoc, the same comment omits the type braces:
/**
* @param id - The unique user identifier.
* @returns The user object if found.
*/
Use Case
Documenting API client methods, database query functions, file I/O operations, and any function that performs asynchronous work. Essential for SDK and library authors who need to communicate both success and failure paths.