API Documentation with JSDoc Examples

Introduction to JSDoc for API Documentation

In the realm of software development, maintaining clear and concise API documentation is crucial for ensuring that users can effectively interact with your code. JSDoc is a popular tool for generating documentation from annotated JavaScript source code. This article provides diverse examples of creating API documentation with JSDoc, showcasing its versatility and effectiveness.

Example 1: Documenting a Simple Function

Context

This example illustrates how to document a basic JavaScript function that adds two numbers. Documenting simple functions is essential for clarity, especially when the function will be reused across multiple projects.

/**

 * Adds two numbers together.
 * @param {number} a - The first number to add.
 * @param {number} b - The second number to add.
 * @returns {number} The sum of the two numbers.
 */
function add(a, b) {
    return a + b;
}

Notes

• Use the @param tag to describe the parameters, including their types and purpose.
• The @returns tag clearly indicates what the function outputs.
• This structured format helps future developers quickly understand the function’s purpose and usage.

Example 2: Documenting a Class with Methods

Context

In this example, we will document a JavaScript class representing a basic calculator. Documenting classes and their methods provides a comprehensive view of how to use the class effectively.

/**

 * Represents a simple calculator.
 */
class Calculator {
    /**

     * Adds two numbers.
     * @param {number} a - The first number.
     * @param {number} b - The second number.
     * @returns {number} The sum of a and b.
     */
    add(a, b) {
        return a + b;
    }

    /**

     * Subtracts the second number from the first.
     * @param {number} a - The number to subtract from.
     * @param {number} b - The number to subtract.
     * @returns {number} The result of a - b.
     */
    subtract(a, b) {
        return a - b;
    }
}

Notes

• Each method is documented with a clear description and parameter details.
• This format allows users to see all available methods at a glance, enhancing usability.

Example 3: Documenting an Asynchronous API Call

Context

This example demonstrates how to document an asynchronous function that fetches data from an API. This is particularly useful in modern web applications where developers need to handle asynchronous operations.

/**

 * Fetches user data from the API.
 * @async
 * @param {string} userId - The ID of the user to fetch data for.
 * @returns {Promise<Object>} A promise that resolves to the user data.
 * @throws {Error} Throws an error if the fetch fails.
 */
async function fetchUserData(userId) {
    const response = await fetch(`https://api.example.com/users/${userId}`);
    if (!response.ok) {
        throw new Error('Network response was not ok');
    }
    return await response.json();
}

Notes

• The @async tag indicates that the function returns a promise.
• Clearly stating potential errors helps users understand the risks involved when calling the function.
• This example demonstrates how to document more complex interactions with APIs, making it a vital part of modern API documentation practices.