ArticleZip > How To Exclude Some Fields From The Document

How To Exclude Some Fields From The Document

Documenting your code is essential for maintaining clarity and understanding for yourself and others who may work with your code. However, there are times when you may want to exclude certain fields from being documented in order to keep your documentation concise and relevant. In this article, we will explore how to exclude specific fields from the document when using documentation generators like JSDoc or similar tools.

One common scenario where you might want to exclude fields is when you have internal or private properties that are not meant to be exposed or documented for external use. By excluding these fields from the generated documentation, you can ensure that only the relevant information is included for users of your code.

When working with JSDoc or similar tools, you can use special annotations to exclude specific fields from the generated documentation. One commonly used tag for this purpose is `@private`. By adding `@private` to a field's documentation, you are indicating that the field should not be included in the generated output.

For example, let's say you have a class with both public and private properties, like this:

Js

/**
 * Represents a car object.
 * @class
 */
class Car {
    /**
     * Create a new Car instance.
     * @param {string} model - The car's model.
     * @param {string} make - The car's make.
     */
    constructor(model, make) {
        this.model = model;
        this.make = make;
        this._vin = generateVin();
    }

    /**
     * Get the car's VIN (Vehicle Identification Number).
     * @returns {string} The car's VIN.
     */
    getVin() {
        return this._vin;
    }
}

In this example, the `_vin` property is marked as private using the underscore convention. To exclude this private field from the generated documentation, you can add the `@private` tag to the field's JSDoc comment, like this:

Js

/**
 * Create a new Car instance.
 * @param {string} model - The car's model.
 * @param {string} make - The car's make.
 */
constructor(model, make) {
    this.model = model;
    this.make = make;
    /**
 * @private
 */
    this._vin = generateVin();
}

By adding `@private` to the `_vin` field's documentation, you are signaling to the documentation tool that this field should be excluded from the generated output.

It's important to use these exclusion annotations judiciously and only for fields that are truly private or internal to your code. Overusing exclusion annotations can make your documentation less helpful and potentially confusing for users of your code.

In conclusion, excluding fields from your code documentation can help you maintain a clean and concise documentation output, especially when dealing with private or internal properties. By using annotations like `@private` in your JSDoc comments, you can control which fields are included in the generated documentation and provide a more focused documentation experience for users of your code.

Related posts:

×