DOCSEARCHbyAlgolia
Submit Docs

JSDoc Documentation

website·Indexed 29 days ago

https://vjsdoc.netlify.app/

Documentation for JSDoc 3, featuring a comprehensive dictionary of tags such as @param, @returns, @module, and @interface. Includes guides on documenting CommonJS, AMD, and ECMAScript 2015 modules.

Tokens
26.7K
Snippets
184
Records
207
Agent score
74%

What's inside JSDoc

  1. Provide a concise description using the @summary tag

    The @summary tag allows you to define a shorter version of the full description for any doclet. This is useful when the main description is too verbose and a brief overview is needed for summaries or index pages.
    /**
 * A very long, verbose, wordy, long-winded, tedious, verbacious, tautological,
 * profuse, expansive, enthusiastic, redundant, flowery, eloquent, articulate,
 * loquacious, garrulous, chatty, extended, babbling description.
 * @summary A concise summary.
 */
function bloviate() {}

  2. Document copyright information using the @copyright tag

    The @copyright tag is used within a file overview comment to document copyright information. It should be used in conjunction with the @file tag to provide a complete file header.
    /**
 * @file This is my cool script.
 * @copyright Michael Mathews 2011
 */

  3. Describe a file using the @file JSDoc tag

    The @file tag is used to provide a description for an entire file. To document a file, place the @file tag within a JSDoc comment at the very beginning of the file.

    Common synonyms for this tag include fileoverview and overview.

    /**
 * @file Manages the configuration settings for the widget.
 * @author Rowina Sanela <rsanela@example.com>
 */

  4. Document an event using a named doclet

    Events can be documented separately from the method that fires them by using a standalone named doclet. This keeps the method documentation concise while still providing full details about the event's properties.
    /**
 * Throw a snowball.
 *
 * @fires Hurl#snowball
 */
Hurl.prototype.snowball = function() {
    // ...
};

/**
 * Snowball event.
 *
 * @event Hurl#snowball
 * @type {object}
 * @property {boolean} isPacked - Indicates whether the snowball is tightly packed.
 */

  5. Use JSDoc block tags for structured documentation

    Block tags are used at the top level of a JSDoc comment to provide detailed information about code (e.g., parameters). They must begin with an at sign (@) and must be followed by a line break, unless the tag is the final element in the JSDoc comment.
    /**
 * Set the color and type of the shoelaces.
 *
 * @param {LACE_COLORS} color - The shoelace color.
 * @param {LACE_TYPES} type - The type of shoelace.
 */
Shoe.prototype.setLaceType = function(color, type) {
    // ...
};

  6. Identify external symbols using the @external tag

    The @external tag identifies a class, namespace, or module defined outside of the current package. This allows developers to document extensions to external symbols or provide reference information about them.

    When referring to an external symbol in other JSDoc tags (like @augments or {@link}), you must use the external: prefix (e.g., external:Foo). However, the prefix is omitted when using the @external tag itself.

    Constraint: Only apply the @external tag to the highest-level symbol defined outside your project. For nested symbols, use @memberof external:ParentName instead of another @external tag.

    /**
 * @external <NameOfExternal>
 */

  7. Use JSDoc tags to provide detailed API metadata

    JSDoc tags (starting with @) provide structured information about the code. Common tags include @constructor to identify class constructors and @param to define method parameters, including their type and description.
    /**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
}

  8. Define and reference callback functions using @callback

    The @callback tag is used to document a callback function that can be passed to other functions. It allows you to define the callback's parameters and return value, effectively creating a custom type. Once defined, the callback's name can be used as a type in @param or @returns tags to indicate that a function parameter must adhere to that specific callback signature.

    To associate a callback with a specific class, use a namepath (e.g., ClassName~callbackName). Otherwise, defining it with just a name creates a global callback type.

    /**
 * @callback MyCallback
 * @param {number} statusCode
 * @param {string} message
 */

/**
 * @param {MyCallback} cb - The callback to execute
 */
function performAction(cb) {
  cb(200, 'Success');
}

  9. Document a JavaScript module using @module

    The @module tag marks the current file as its own module. All symbols within that file are assumed to be members of the module unless documented otherwise.

    If a module name is provided, it is used as the identifier. If omitted, JSDoc derives the name from the file path and filename. For example, if test.js is in the src directory and contains /** @module */:

    • Running jsdoc ./test.js results in module name test.
    • Running jsdoc src/test.js results in module name src/test.
    • Running jsdoc -r src/ results in module name test.

    To link to a module (using {@link} or @see), use the module: prefix followed by the module name (e.g., {@link module:foo/bar}).

    /** @module myModuleName */

  10. Use type expressions within other JSDoc tags

    Type expressions do not always require a standalone @type tag. They can be appended directly to other compatible tags, such as @const, to reduce verbosity while maintaining type information.
    /**
 * @type {number}
 * @const
 */
var FOO = 1;

// Equivalent shorthand:

/** @const {number} */
var FOO = 1;

  11. Document AMD module identifiers in JSDoc

    To document an AMD module, use the @exports or @module tag with the identifier passed to the require() function. If the tag is used without a value, JSDoc attempts to guess the identifier based on the file path. When referencing an AMD module from another comment using a namepath, you must prefix the identifier with module:. For example, a member of module my/pants named Jeans with a method hem would have the longname module:my/pants.Jeans#hem.
    /**
 * Pants module.
 * @module my/pants
 * @see module:my/shirt
 */

  12. Handle special characters in namepaths using quotes

    If a member name contains special characters (such as hashes, dashes, or quotes), the specific segment of the namepath must be enclosed in double quotes. Internal quotes within the name must be escaped with a backslash.
    /** @namespace */
var chat = {
    "#channel": {
        open: true,
        'say-"hello"': function (msg) {}
    }
};

// Examples of referencing these in JSDoc:
// {@link chat."#channel"}
// {@link chat."#channel".open}
// {@link chat."#channel"."say-\"hello\""}