### Install Project Dependencies

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/README.md

Run this command in the project's root directory to install all necessary Node.js dependencies.

```bash
npm install
```

--------------------------------

### Basic Namepath Syntax Examples

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-namepaths.md

Illustrates the fundamental syntax for various types of JavaScript members.

```javascript
myFunction
MyConstructor
MyConstructor#instanceMember
MyConstructor.staticMember
MyConstructor~innerMember // note that JSDoc 2 uses a dash
```

--------------------------------

### Documenting Examples with @example

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-example.md

Use the @example tag to provide code snippets demonstrating how to use a documented item. Multiple @example tags can be used for a single item.

```js
/**
 * Solves equations of the form a * x = b
 * @example
 * // returns 2
 * globalNS.method1(5, 10);
 * @example
 * // returns 3
 * globalNS.method(5, 15);
 * @returns {Number} Returns the value of x for the equation.
 */
globalNS.method1 = function (a, b) {
    return b / a;
};
```

--------------------------------

### Documenting Examples with Captions

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-example.md

You can add captions to your @example tags by including `<caption>` text immediately after the tag. This provides context for the example.

```js
/**
 * Solves equations of the form a * x = b
 * @example &lt;caption>Example usage of method1.&lt;/caption>
 * // returns 2
 * globalNS.method1(5, 10);
 * @returns {Number} Returns the value of x for the equation.
 */
globalNS.method1 = function (a, b) {
    return b / a;
};
```

--------------------------------

### Serve JSDoc Documentation Locally

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/README.md

After making changes, use this command to rebuild the HTML files and start a local development server for previewing.

```bash
npm run serve
```

--------------------------------

### JSDoc Tutorials Configuration

Source: https://context7.com/jsdoc/jsdoc.github.io/llms.txt

Provides examples for configuring JSDoc tutorials, including command-line usage for generating docs with tutorials and a JSON structure for defining tutorial titles and hierarchy.

```bash
# Generate docs with tutorials from a directory
jsdoc src/ -u path/to/tutorials -d docs
```

```json
// path/to/tutorials/tutorials.json — title and hierarchy:
{
    "getting-started": {
        "title": "Getting Started",
        "children": {
            "installation": { "title": "Installation" },
            "quickstart":   { "title": "Quick Start" }
        }
    },
    "advanced": { "title": "Advanced Usage" }
}
```

```javascript
/**
 * Class representing a socket connection.
 *
 * @class
 * @tutorial getting-started
 */
function Socket() {}

/**
 * Send a message over the socket.
 * See {@tutorial advanced} for performance tips.
 *
 * @param {string} msg - The message to send.
 */
Socket.prototype.send = function(msg) {};
```

--------------------------------

### Run JSDoc from Command Line

Source: https://context7.com/jsdoc/jsdoc.github.io/llms.txt

Examples of running JSDoc from the command line to document JavaScript files and directories. Includes common flags for recursion, configuration, output, and filtering.

```bash
# Basic: document a single file
jsdoc yourSourceCodeFile.js
```

```bash
# Recurse a directory, use a config file, output to ./docs
jsdoc src/ -r -c /path/to/conf.json -d docs
```

```bash
# Include private symbols and a README on the front page
jsdoc src/ -r -p -R README.md -d docs
```

```bash
# Dump all doclets as JSON (useful for debugging)
jsdoc src/ -X
```

```bash
# Use a custom template
jsdoc src/ -t path/to/my-template -d docs
```

```bash
# Add tutorial pages from a directory
jsdoc src/ -u path/to/tutorials -d docs
```

```bash
# Run with verbose output
jsdoc src/ --verbose
```

```bash
# Key flags:
#   -a <value>   --access      Filter by access level: private|protected|public|all
#   -c <value>   --configure   Path to configuration file
#   -d <value>   --destination Output folder (default: ./out)
#   -e <value>   --encoding    Source file encoding (default: utf8)
#   -p           --private     Include @private symbols
#   -P           --package     Specify package.json to use
#   -r           --recurse     Recurse into subdirectories
#   -R           --readme      README.md to include on front page
#   -t <value>   --template    Path to output template
#   -u <value>   --tutorials   Directory of tutorial files
#   --pedantic                 Treat warnings as errors
```

--------------------------------

### Clone JSDoc Documentation Repository

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/README.md

Use this command to get a local copy of the JSDoc documentation repository.

```bash
git clone https://github.com/jsdoc/jsdoc.github.io
```

--------------------------------

### JSDoc Configuration File Example

Source: https://context7.com/jsdoc/jsdoc.github.io/llms.txt

A sample JSON configuration file for JSDoc, specifying plugins, recursion depth, source file inclusion/exclusion patterns, tag dictionaries, and template options.

```json
{
    "plugins": ["plugins/markdown", "plugins/summarize"],
    "recurseDepth": 10,
    "source": {
        "include": ["src/", "lib/"],
        "exclude": ["src/vendor"],
        "includePattern": ".+\.js(doc|x)?$",
        "excludePattern": "(^|\/|\\)_"
    },
    "sourceType": "module",
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc", "closure"]
    },
    "templates": {
        "cleverLinks": true,
        "monospaceLinks": false,
        "default": {
            "outputSourceFiles": true,
            "includeDate": false,
            "useLongnameInNav": false,
            "layoutFile": "path/to/custom/layout.tmpl",
            "staticFiles": {
                "include": ["./myproject/static"],
                "exclude": [],
                "includePattern": ".+\.(png|jpg|css)$"
            }
        }
    },
    "opts": {
        "destination": "./docs",
        "recurse": true,
        "readme": "README.md",
        "tutorials": "path/to/tutorials",
        "encoding": "utf8"
    }
}
```

--------------------------------

### Namepath Syntax for Modules, Externals, and Events

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-namepaths.md

Provides examples of namepath prefixes for special JSDoc types: modules ('module:'), externals ('external:'), and events ('event:').

```javascript
/** A module. Its name is module:foo/bar.
 * @module foo/bar
 */
/** The built in string object. Its name is external:String.
 * @external String
 */
/** An event. Its name is module:foo/bar.event:MyEvent.
 * @event module:foo/bar.event:MyEvent
 */
```

--------------------------------

### JSDoc Namepath Examples

Source: https://context7.com/jsdoc/jsdoc.github.io/llms.txt

Demonstrates how to use JSDoc namepaths to uniquely identify symbols within a library, including instance, static, inner members, and members with special characters.

```javascript
/** @namespace */
var MyLib = {};

/** @constructor */
MyLib.Formatter = function() {
    /** @type {string} */
    this.locale = 'en';

    // Instance method: MyLib.Formatter#format
    this.format = function(val) { return String(val); };
};

// Static method: MyLib.Formatter.create
MyLib.Formatter.create = function(opts) {
    return new MyLib.Formatter();
};

/**
 * @namespace chat
 */
var chat = {
    /**
     * Refer to this by {@link chat."#channel"}.
     * @namespace
     */
    "#channel": {
        /** @type {boolean} */
        open: true,
        /** @param {string} msg */
        'say-"hello"': function(msg) {}
    }
};

// Namepath examples:
// MyLib.Formatter#format   → instance method
// MyLib.Formatter.create   → static method
// chat."#channel".open     → property with special chars
// module:my/pants.Jeans#hem → module member instance method
```

--------------------------------

### Add a Simple Description to a Function

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-getting-started.md

Use a JSDoc comment starting with /** to provide a description for a function.

```javascript
/** This is a description of the foo function. */
function foo() {
}
```

--------------------------------

### Equivalent to @var using @type

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-member.md

This example shows how the @var tag is equivalent to using the @type tag with a variable declaration.

```javascript
/**
 * A variable in the global namespace called 'foo'.
 * @type {number}
 */
var foo;
```

--------------------------------

### JSDoc Inline Link Tag Examples

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-inline-link.md

Demonstrates various ways to use the `{@link}` inline tag to link to documentation items and URLs, including providing custom link text.

```javascript
/**
 * See {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}.
 * Also, check out {@link http://www.google.com|Google} and
 * {@link https://github.com GitHub}.
 */
function myFunction() {}
```

--------------------------------

### Documenting 'this' with @this Tag

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-this.md

Use the @this tag to specify what the 'this' keyword refers to within a function. This example shows how '@this Greeter' ensures 'this.name' is documented as 'Greeter#name'.

```javascript
/** @constructor */
function Greeter(name) {
    setName.apply(this, name);
}

/** @this Greeter */
function setName(name) {
    /** document me */
    this.name = name;
}
```

--------------------------------

### Using the @private tag

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-private.md

This example demonstrates how to use the @private tag to exclude a member from generated documentation. 'Documents' and 'Documents.Newspaper' will be documented, but 'Documents.Diary' will not.

```js
/** @namespace */
var Documents = {
    /**
     * An ordinary newspaper.
     */
    Newspaper: 1,
    /**
     * My diary.
     * @private
     */
    Diary: 2
};
```

--------------------------------

### File Description with @file Tag

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-file.md

Use the @file tag in a JSDoc comment at the beginning of the file to describe its purpose. This example also includes an @author tag.

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

--------------------------------

### Documenting an Event and its Listener with @listens

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-listens.md

This example demonstrates how to document an event using the @event tag and a method that listens for that event using the @listens tag. The @fires tag is also used to indicate that the attack method emits the snowball event.

```javascript
define('hurler', [], function () {
    /**
     * Event reporting that a snowball has been hurled.
     *
     * @event module:hurler~snowball
     * @property {number} velocity - The snowball's velocity, in meters per second.
     */

    /**
     * Snowball-hurling module.
     *
     * @module hurler
     */
    var exports = {
        /**
         * Attack an innocent (or guilty) person with a snowball.
         *
         * @method
         * @fires module:hurler~snowball
         */
        attack: function () {
            this.emit('snowball', { velocity: 10 });
        }
    };

    return exports;
});

define('playground/monitor', [], function () {
    /**
     * Keeps an eye out for snowball-throwers.
     *
     * @module playground/monitor
     */
    var exports = {
        /**
         * Report the throwing of a snowball.
         *
         * @method
         * @param {module:hurler~event:snowball} e - A snowball event.
         * @listens module:hurler~event:snowball
         */
        reportThrowage: function (e) {
            this.log('snowball thrown: velocity ' + e.velocity);
        }
    };

    return exports;
});
```

--------------------------------

### Define a Constructor Function with @class

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-class.md

Use the @class tag to document functions that are meant to be called with the 'new' keyword to create instances. This example shows a basic constructor for 'Person' objects.

```javascript
/**
 * Creates a new Person.
 * @class
 */
function Person() {
}

var p = new Person();
```

--------------------------------

### Defining Exported Symbols with 'module.exports' or 'exports'

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-module.md

Demonstrates documenting exported functions as static members of a module when they are assigned to 'module.exports' or 'exports'. This example defines 'blend' and 'darken' functions for the 'color/mixer' module.

```javascript
/** @module color/mixer */
module.exports = {
    /** Blend two colours together. */
    blend: function (color1, color2) {}
};
/** Darkens a color. */
exports.darken = function (color, shade) {};
```

--------------------------------

### Using @constructs without @lends

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-constructs.md

When not using @lends, you must explicitly provide the name of the class that the function constructs. This example shows a class named 'Menu'.

```javascript
makeClass('Menu',
    /**
     * @constructs Menu
     * @param items
     */
    function (items) { },
    {
        /** @memberof Menu# */
        show: function(){
        }
    }
);

```

--------------------------------

### Link to Tutorial using {@tutorial} Inline Tag

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-tutorials.md

Embed the `{@tutorial}` inline tag within JSDoc comments to link to a tutorial. JSDoc automatically uses the tutorial's title as the link text, providing a seamless way to reference related guides.

```javascript
/**
 * Class representing a socket connection. See {@tutorial socket-tutorial}
 * for an overview.
 *
 * @class
 */
function Socket() {}
```

--------------------------------

### Documenting Modules with @module

Source: https://context7.com/jsdoc/jsdoc.github.io/llms.txt

Use the @module tag to mark a file as a module, creating a namespace for its symbols. This works with CommonJS, ES2015, and AMD patterns. The example shows ES2015 exports and a CommonJS equivalent.

```javascript
/** @module color/mixer */

// ES2015 module exports
export const name = 'mixer';
export var lastColor = null;

/**
 * Blend two colors together.
 * @param {string} color1 - First color in hex.
 * @param {string} color2 - Second color in hex.
 * @return {string} The blended color.
 */
export function blend(color1, color2) {}
```

```javascript
// --- CommonJS equivalent ---
/**
 * Color mixer (CommonJS).
 * @module color/mixer
 */
module.exports = {
    /** @param {string} c1 @param {string} c2 @return {string} */
    blend(c1, c2) {},

    /** @param {string} color @param {number} pct @return {string} */
    darken(color, pct) {}
};
// Reference another module: @see module:color/mixer
```

--------------------------------

### Basic @module Usage

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-module.md

Illustrates the basic usage of the @module tag to define a module named 'myModule'. It shows how variables declared within the module scope get their namepaths, distinguishing between module-private and exported members.

```javascript
/** @module myModule */

/** will be module:myModule~foo */
var foo = 1;

/** will be module:myModule.bar */
var bar = function() {};
```

--------------------------------

### Defining Exported Symbols with 'this'

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-module.md

Shows how to document exported symbols as static members of a module when they are defined as properties of 'this' within the module scope. This example documents a 'Book' class for the 'bookshelf' module.

```javascript
/** @module bookshelf */
/** @class */
this.Book = function (title) {
    /** The title. */
    this.title = title;
};
```

--------------------------------

### Handle newDoclet Event in JSDoc Plugin

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-plugins.md

Use this handler to modify newly created doclets. The example converts the doclet's description to uppercase. Ensure the description is a string before attempting modification.

```javascript
exports.handlers = {
    newDoclet: function(e) {
        // e.doclet will refer to the newly created doclet
        // you can read and modify properties of that doclet if you wish
        if (typeof e.doclet.description === 'string') {
            e.doclet.description = e.doclet.description.toUpperCase();
        }
    }
};
```

--------------------------------

### Documenting ES2015 Classes and Inheritance

Source: https://context7.com/jsdoc/jsdoc.github.io/llms.txt

JSDoc automatically recognizes ES2015 class syntax. Use @augments (or @extends) to document inheritance. The examples show a base Point class and a Dot class that extends Point, including constructors and methods.

```javascript
/** Class representing a point in 2D space. */
class Point {
    /**
     * Create a point.
     * @param {number} x - The x value.
     * @param {number} y - The y value.
     */
    constructor(x, y) {
        this._x = x;
        this._y = y;
    }

    /** @return {number} The x value. */
    getX() { return this._x; }

    /** @return {number} The y value. */
    getY() { return this._y; }

    /**
     * Parse "x,y" into a Point.
     * @param {string} str - Comma-separated coordinate string.
     * @return {Point}
     */
    static fromString(str) {
        const [x, y] = str.split(',').map(Number);
        return new Point(x, y);
    }
}

/**
 * A colored dot that extends Point.
 * @augments Point
 */
class Dot extends Point {
    /**
     * @param {number} x
     * @param {number} y
     * @param {string} color - CSS color value.
     */
    constructor(x, y, color) {
        super(x, y);
        this.color = color;
    }
}

// Usage:
const p = Point.fromString('3,4');   // Point { _x: 3, _y: 4 }
const d = new Dot(1, 2, 'red');      // Dot { _x: 1, _y: 2, color: 'red' }
```

--------------------------------

### Configure Tutorial Hierarchy with JSON (Array Format)

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-tutorials.md

An alternative JSON format for configuring tutorial hierarchy. This method lists child tutorials by name in an array within the parent's `children` property, with each tutorial defined as a top-level object.

```json
{
    "tutorial1": {
        "title": "Tutorial One",
        "children": ["childA", "childB"]
    },
    "tutorial2": {
        "title": "Tutorial Two"
    },
    "childA": {
        "title": "Child A"
    },
    "childB": {
        "title": "Child B"
    }
}
```

--------------------------------

### Run JSDoc with Tutorials Directory

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-tutorials.md

Use the `--tutorials` or `-u` option with JSDoc to specify a directory containing your tutorial files. JSDoc will automatically discover and process files with extensions like .htm, .html, .md, and .xml.

```bash
jsdoc -u path/to/tutorials path/to/js/files
```

--------------------------------

### Documenting a Mixin Object with @mixin

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-mixin.md

Use the @mixin tag to indicate that an object is a mixin. This example shows a mixin for event handling functionality.

```javascript
/**
 * This provides methods used for event handling. It's not meant to
 * be used directly.
 *
 * @mixin
 */
var Eventful = {
    /**
     * Register a handler function to be called whenever this event is fired.
     * @param {string} eventName - Name of the event.
     * @param {function(Object)} handler - The handler to call.
     */
    on: function(eventName, handler) {
        // code...
    },

    /**
     * Fire an event, causing all handlers for that event name to run.
     * @param {string} eventName - Name of the event.
     * @param {Object} eventData - The data provided to each handler.
     */
    fire: function(eventName, eventData) {
        // code...
    }
};
```

--------------------------------

### JSON configuration file with command-line options

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-configuring-jsdoc.md

Use the 'opts' section to specify command-line options within a JSON configuration file. Command-line arguments take precedence over configuration file settings.

```json
{
    "opts": {
        "template": "templates/default",  // same as -t templates/default
        "encoding": "utf8",               // same as -e utf8
        "destination": "./out/",          // same as -d ./out/
        "recurse": true,                  // same as -r
        "tutorials": "path/to/tutorials", // same as -u path/to/tutorials
    }
}
```

--------------------------------

### Using @readonly with a Getter

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-readonly.md

The @readonly tag can be used with getters to document properties that are computed and should not be directly assigned to. This example shows its use within an object literal.

```javascript
/**
 * Options for ordering a delicious slice of pie.
 * @namespace
 */
var pieOptions = {
	/**
	 * Plain.
	 */
	plain: 'pie',
	/**
	 * A la mode.
	 * @readonly
	 */
	get aLaMode() {
		return this.plain + ' with ice cream';
	}
};
```

--------------------------------

### Configure Tutorial Hierarchy with JSON (Tree Format)

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-tutorials.md

Define the title, sorting, and hierarchy of your tutorials using a JSON file. This format uses nested objects to represent parent-child relationships, where the `children` property lists sub-tutorials.

```json
{
    "tutorial1": {
        "title": "Tutorial One",
        "children": {
            "childA": {
                "title": "Child A"
            },
            "childB": {
                "title": "Child B"
            }
        }
    },
    "tutorial2": {
        "title": "Tutorial Two"
    }
}
```

--------------------------------

### Provide Link Text for Tutorial Tag

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-inline-tutorial.md

Demonstrates the different ways to provide link text when using the `{@tutorial}` inline tag. Use this when you need to link to a specific tutorial and customize the displayed link text.

```javascript
/**
 * See {@tutorial gettingstarted} and [Configuring the Dashboard]{@tutorial dashboard}.
 * For more information, see {@tutorial create|Creating a Widget} and
 * {@tutorial destroy Destroying a Widget}.
 */
function myFunction() {}
```

--------------------------------

### Generate Documentation from Command Line

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-getting-started.md

Run the JSDoc tool from the command line, specifying the source JavaScript files to generate HTML documentation.

```bash
jsdoc book.js
```

--------------------------------

### Use @alias for an object literal

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-alias.md

Document members of an object literal using @alias, similar to how @lends works. This example shows 'objectA.myProperty' being documented correctly.

```javascript
// Documenting objectA with @alias

var objectA = (function() {

    /**
     * Documented as objectA
     * @alias objectA
     * @namespace
     */
    var x = {
        /**
         * Documented as objectA.myProperty
         * @member
         */
        myProperty: 'foo'
    };

    return x;
})();

// Documenting objectB with @lends

/**
 * Documented as objectB
 * @namespace
 */
var objectB = (function() {

    /** @lends objectB */
    var x = {
        /**
         * Documented as objectB.myProperty
         * @member
         */
        myProperty: 'bar'
    };

    return x;
})();
```

--------------------------------

### Using the @tutorial Tag

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-tutorial.md

Use the @tutorial tag to link to tutorials with specific identifiers. This tag can be used multiple times in a single JSDoc comment.

```javascript
/**
 * Description
 * @class
 * @tutorial tutorial-1
 * @tutorial tutorial-2
 */
function MyClass() {}
```

--------------------------------

### Describing Instance, Inner, and Static Methods

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-namepaths.md

Demonstrates how to define and differentiate instance, inner, and static methods within a constructor. Instance and static methods are directly accessible, while inner functions are not.

```javascript
/** @constructor */
Person = function() {
    this.say = function() {
        return "I'm an instance.";
    }

    function say() {
        return "I'm inner.";
    }
}
Person.say = function() {
    return "I'm static.";
}

var p = new Person();
p.say();      // I'm an instance.
Person.say(); // I'm static.
// there is no way to directly access the inner function from here
```

--------------------------------

### Using the @name Tag

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-name.md

Use the @name tag to document a function that JSDoc would not normally recognize. This example documents a function generated at runtime using eval.

```js
/**
 * @name highlightSearchTerm
 * @function
 * @global
 * @param {string} term - The search term to highlight.
 */
eval("window.highlightSearchTerm = function(term) {};")
```

--------------------------------

### Generate JSDoc documentation with custom configuration and output

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-commandline.md

Use this command to generate documentation for files in a specified directory, applying a custom configuration file and directing the output to a specific folder. The `-r` flag enables recursive scanning of subdirectories.

```bash
/path/to/jsdoc src -r -c /path/to/my/conf.json -d docs
```

--------------------------------

### Modify Source Code Before Parsing

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-plugins.md

Use the 'beforeParse' event handler to modify the source code before JSDoc parses it. This example adds a virtual JSDoc comment for a function.

```js
exports.handlers = {
    beforeParse: function(e) {
        var extraDoc = [
            '/**',
            ' * Function provided by a superclass.',
            ' * @name superFunc',
            ' * @memberof ui.mywidget',
            ' * @function',
            ' */'
        ];
        e.source += extraDoc.join('\n');
    }
};
```

--------------------------------

### Link to Tutorial using @tutorial Block Tag

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-tutorials.md

Use the `@tutorial` block tag within a JSDoc comment to create a link to a specific tutorial. The tag's value should be the tutorial's identifier (filename without extension).

```javascript
/**
 * Class representing a socket connection.
 *
 * @class
 * @tutorial socket-tutorial
 */
function Socket() {}
```

--------------------------------

### Referring to Instance, Static, and Inner Methods

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-namepaths.md

Shows the specific namepath syntax required to reference instance, static, and inner methods defined within a constructor.

```javascript
Person#say  // the instance method named "say."
Person.say  // the static method named "say."
Person~say  // the inner method named "say."
```

--------------------------------

### Define Event Handler Plugin

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-plugins.md

Export an 'handlers' object from your plugin module to register functions for specific JSDoc events. This example shows a handler for the 'newDoclet' event.

```js
exports.handlers = {
    newDoclet: function(e) {
        // Do something when we see a new doclet
    }
};
```

--------------------------------

### Rename a function with @alias

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-alias.md

Use the @alias tag to rename a function in the documentation without changing its actual code name. This example shows how 'foo' is documented as 'bar'.

```javascript
/**
 * Bar function.
 * @alias bar
 */
function foo() {}
```

--------------------------------

### Rendered HTML Output for Tutorial Links

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-inline-tutorial.md

Shows the expected HTML output generated by JSDoc for the `{@tutorial}` tags when tutorials are defined. This illustrates how JSDoc converts the inline tags into anchor `<a>` elements.

```html
See &lt;a href="tutorial-gettingstarted.html">Getting Started&lt;/a> and
&lt;a href="tutorial-dashboard.html">Configuring the Dashboard&lt;/a>.
For more information, see &lt;a href="tutorial-create.html">Creating a Widget&lt;/a> and
&lt;a href="tutorial-destroy.html">Destroying a Widget&lt;/a>.
```

--------------------------------

### JSON configuration file with multiple plugins

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-configuring-jsdoc.md

Enable multiple JSDoc plugins, such as Markdown and summarize, by listing them in the 'plugins' array within your JSON configuration.

```json
{
    "plugins": [
        "plugins/markdown",
        "plugins/summarize"
    ]
}
```

--------------------------------

### Method that fires a 'drain' event

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-fires.md

Use the @fires tag to indicate that a method can fire a specified event. This example shows a method that fires a 'drain' event on a Milkshake object.

```javascript
/**
 * Drink the milkshake.
 *
 * @fires Milkshake#drain
 */
Milkshake.prototype.drink = function() {
    // ...
};
```

--------------------------------

### AMD Module Exporting Object Literal

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-exports.md

This example shows an AMD module that exports an object literal. JSDoc automatically recognizes members of the 'exports' object as module exports.

```javascript
define(function() {

    /**
     * A module that whispers hello!
     * @module hello/world
     */
    var exports = {};

    /** say hello. */
    exports.sayHello = function() {
        return 'hello world';
    };

    return exports;
});
```

--------------------------------

### Documenting Function Parameters with JSDoc

Source: https://context7.com/jsdoc/jsdoc.github.io/llms.txt

Demonstrates how to use JSDoc's `@param` tag to document function parameters, including types, optional values, default values, destructured objects, and callback signatures.

```js
/**
 * A number, or a string containing a number.
 * @typedef {(number|string)} NumberLike
 */
```

```js
/**
 * @callback RequestCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */
```

```js
/**
 * Assign the project to a list of employees and call back when done.
 *
 * @param {Object[]} employees - The employees responsible for the project.
 * @param {string}   employees[].name       - Employee's name.
 * @param {string}   employees[].department - Employee's department.
 * @param {NumberLike} [priority=1]         - Priority level (optional, default 1).
 * @param {(string|string[])} [tags]        - Tag or array of tags.
 * @param {...string} notes                 - Any number of extra notes.
 * @param {RequestCallback} cb             - Called on completion.
 */
Project.prototype.assign = function(employees, priority, tags, notes, cb) {
    // ...
};
```

--------------------------------

### Documenting Class Inheritance with @augments

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-augments.md

Use @augments to define a subclass relationship. This example shows a Duck class inheriting from an Animal class, adding a unique 'speak' method.

```javascript
/**
 * @constructor
 */
function Animal() {
    /** Is this animal alive? */
    this.alive = true;
}

/**
 * @constructor
 * @augments Animal
 */
function Duck() {}
Duck.prototype = new Animal();

/** What do ducks say? */
Duck.prototype.speak = function() {
    if (this.alive) {
        alert('Quack!');
    }
};

var d = new Duck();
d.speak(); // Quack!
d.alive = false;
d.speak(); // (nothing)
```

--------------------------------

### Configure template appearance and content

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-configuring-jsdoc.md

Adjust template settings like 'cleverLinks' and 'monospaceLinks' to control how links are rendered in the generated documentation. 'cleverLinks' overrides 'monospaceLinks'.

```json
{
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}
```

--------------------------------

### JSDoc Comment with Markdown

Source: https://context7.com/jsdoc/jsdoc.github.io/llms.txt

This JSDoc comment uses Markdown formatting for descriptions and includes an example of a function call. The Markdown plugin converts the bold text and list items to HTML.

```javascript
/**
 * Parses a **Markdown**-formatted config string.
 *
 * Supported keys:
 * - `host` — server hostname
 * - `port` — server port
 *
 * @param {string} input - The raw config string.
 * @returns {Object} Parsed config object.
 * @throws {SyntaxError} If the input is malformed.
 *
 * @example
 * // Returns { host: 'localhost', port: 8080 }
 * parseConfig('host=localhost\nport=8080');
 */
function parseConfig(input) {}
```

--------------------------------

### Include Package File in Source Paths

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-including-package.md

Specify the path to your package.json file along with your JavaScript source paths. JSDoc will use the first package.json it finds.

```bash
jsdoc path/to/js path/to/package/package.json
```

--------------------------------

### Using @var to document a virtual member

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-member.md

The @var tag, a synonym for @member, can document a virtual member that doesn't have a corresponding code declaration. This example documents a number named 'foo'.

```javascript
/**
 * A variable in the global namespace called 'foo'.
 * @var {number} foo
 */
```

--------------------------------

### Use -P/--package Option

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-including-package.md

Utilize the -P/--package command-line option to specify the path to your package.json file. This method overrides any package.json files found in your source paths and is available in JSDoc 3.3.0 and later.

```bash
jsdoc --package path/to/package/package-docs.json path/to/js
```

--------------------------------

### Hide constructor for pre-ES2015 class

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-hideconstructor.md

Use the @hideconstructor tag within the JSDoc comment for a class to prevent its constructor from appearing in the documentation. This example demonstrates its use with a pre-ES2015 class pattern.

```javascript
/**
 * @classdesc Toaster singleton.
 * @class
 * @hideconstructor
 */
var Toaster = (function() {
    var instance = null;

    function Toaster() {}

    /**
     * Toast an item.
     *
     * @alias toast
     * @memberof Toaster
     * @instance
     * @param {BreadyThing} item - The item to toast.
     * @return {Toast} A toasted bready thing.
     */
    Toaster.prototype.toast = function(item) {};

    return {
        /**
         * Get the Toaster instance.
         *
         * @alias Toaster.getInstance
         * @returns {Toaster} The Toaster instance.
         */
        getInstance: function() {
            if (instance === null) {
                instance = new Toaster();
                delete instance.constructor;
            }

            return instance;
        }
    };
})();
```

--------------------------------

### Include Pattern for Static Files

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-configuring-default-template.md

Use `templates.default.staticFiles.includePattern` with a regular expression to specify which files to copy. If not defined, all files are copied. Available in JSDoc 3.3.0 and later.

```json
{
  "templates": {
    "default": {
      "staticFiles": {
        "includePattern": "\.png$"
      }
    }
  }
}
```

--------------------------------

### Documenting external namespaces with @external

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-external.md

Document external namespaces, such as jQuery plugins, using the @external tag. This example shows how to document the `jQuery.fn` namespace and a custom function `starfairy` within it.

```js
/**
 * The jQuery plugin namespace.
 * @external "jQuery.fn"
 * @see {@link http://learn.jquery.com/plugins/|jQuery Plugins}
 */

/**
 * A jQuery plugin to make stars fly around your home page.
 * @function external:"jQuery.fn".starfairy
 */
```

--------------------------------

### Copying Static Files to Output Directory

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-configuring-default-template.md

Use `templates.default.staticFiles.include` to specify paths for additional static files to be copied to the output directory. Subdirectories are included. Available in JSDoc 3.3.0 and later.

```json
{
  "templates": {
    "default": {
      "staticFiles": {
        "include": [
        	"./myproject/static"
        ]
      }
    }
  }
}
```

--------------------------------

### Include README in Source Paths

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-including-readme.md

Add the path to your README.md file alongside your JavaScript source paths. JSDoc will automatically include the first README.md it finds.

```bash
jsdoc path/to/js path/to/readme/README.md
```

--------------------------------

### Document an Inner Variable as Global with @global

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-global.md

Use the @global tag to ensure a locally defined variable is documented as a global symbol. This example demonstrates assigning an inner variable to the window object.

```js
(function() {
    /** @global */
    var foo = 'hello foo';

    this.foo = foo;
}).apply(window);
```

--------------------------------

### Use @alias for static members of a namespace

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-alias.md

Expose members defined within an IIFE to the outer scope using @alias. This example documents 'core' as 'Apple.Core', making 'Apple.Core.seed' correctly documented.

```javascript
/** @namespace */
var Apple = {};

(function(ns) {
    /**
     * @namespace
     * @alias Apple.Core
     */
    var core = {};

    /** Documented as Apple.Core.seed */
    core.seed = function() {};

    ns.Core = core;
})(Apple);
```

--------------------------------

### Use -R/--readme Option

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-including-readme.md

Specify the path to your README file using the -R or --readme command-line option. This method is available from JSDoc 3.3.0 and overrides any README files found in source paths.

```bash
jsdoc --readme path/to/readme/README path/to/js
```

--------------------------------

### Documenting an AMD Module Returning a Constructor

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/howto-amd-modules.md

For modules exporting a function, like a constructor, use a standalone comment with `@module` and an `@alias` tag to link the function's longname to the module.

```javascript
/**
 * A module representing a jacket.
 * @module my/jacket
 */
define('my/jacket', function() {
    /**
     * Create a new jacket.
     * @class
     * @alias module:my/jacket
     */
    var Jacket = function() {
        // ...
    };

    /** Zip up the jacket. */
    Jacket.prototype.zip = function() {
        // ...
    };

    return Jacket;
});
```

--------------------------------

### Implement AST Node Visitor with `astNodeVisitor`

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-plugins.md

Plugins can process the abstract syntax tree (AST) by exporting an `astNodeVisitor` object with a `visitNode` function. This function is called for each node in the AST, allowing for deep customization.

```javascript
exports.astNodeVisitor = {
    visitNode: function(node, e, parser, currentSourceName) {
        // do all sorts of crazy things here
    }
};

```

--------------------------------

### Document Simple ES 2015 Class

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/howto-es2015-classes.md

Document a simple ES 2015 class with a constructor, instance methods, and a static method. JSDoc automatically detects the class and its constructor.

```js
/** Class representing a point. */
class Point {
    /**
     * Create a point.
     * @param {number} x - The x value.
     * @param {number} y - The y value.
     */
    constructor(x, y) {
        // ...
    }

    /**
     * Get the x value.
     * @return {number} The x value.
     */
    getX() {
        // ...
    }

    /**
     * Get the y value.
     * @return {number} The y value.
     */
    getY() {
        // ...
    }

    /**
     * Convert a string containing two comma-separated numbers into a point.
     * @param {string} str - The string containing two comma-separated numbers.
     * @return {Point} A Point object.
     */
    static fromString(str) {
        // ...
    }
}
```

--------------------------------

### Methods added to the exports object

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/howto-commonjs-modules.md

JSDoc automatically recognizes symbols directly assigned to a property of the `exports` object as exported symbols. This example shows documenting methods `button` and `unbutton` for the `my/shirt` module.

```javascript
/**
 * Shirt module.
 * @module my/shirt
 */

/** Button the shirt. */
exports.button = function() {
    // ...
};

/** Unbutton the shirt. */
exports.unbutton = function() {
    // ...
};
```

--------------------------------

### Namespace with Child Class and @ignore Tag

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-ignore.md

When using @ignore on a namespace, ensure it's also applied to child classes or namespaces to avoid incomplete documentation. This example shows how to ignore a namespace and its nested class.

```js
/**
 * @namespace
 * @ignore
 */
var Clothes = {
    /**
     * @class
     * @ignore
     */
    Jacket: function() {
        /** The jacket's color. */
        this.color = null;
    }
};
```

--------------------------------

### Documenting Class Members with @memberof

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-memberof.md

Demonstrates various ways to use @memberof for static and instance members of a class. For instance members, use '.prototype' or '#' with the class name, or combine @memberof with the @instance tag.

```javascript
/** @class Observable */
create(
    'Observable',
    {
        /**
         * This will be a static member, Observable.cache.
         * @memberof Observable
         */
        cache: [],

        /**
         * This will be an instance member, Observable#publish.
         * @memberof Observable.prototype
         */
        publish: function(msg) {},

        /**
         * This will also be an instance member, Observable#save.
         * @memberof Observable#
         */
        save: function() {},

        /**
         * This will also be an instance member, Observable#end.
         * @memberof Observable
         * @instance
         */
        end: function() {}
    }
);
```

--------------------------------

### Using the @implements Tag in JSDoc

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-implements.md

Demonstrates how to use the @implements tag to specify that a class fulfills the contract of an interface. The example shows an interface 'Color' and a class 'TransparentColor' that implements it, inheriting documentation for shared methods.

```javascript
/**
 * Interface for classes that represent a color.
 *
 * @interface
 */
function Color() {}

/**
 * Get the color as an array of red, green, and blue values, represented as
 * decimal numbers between 0 and 1.
 *
 * @returns {Array<number>} An array containing the red, green, and blue values,
 * in that order.
 */
Color.prototype.rgb = function() {
    throw new Error('not implemented');
};

/**
 * Class representing a color with transparency information.
 *
 * @class
 * @implements {Color}
 */
function TransparentColor() {}

// inherits the documentation from `Color#rgb`
TransparentColor.prototype.rgb = function() {
    // ...
};

/**
 * Get the color as an array of red, green, blue, and alpha values, represented
 * as decimal numbers between 0 and 1.
 *
 * @returns {Array<number>} An array containing the red, green, blue, and alpha
 * values, in that order.
 */
TransparentColor.prototype.rgba = function() {
    // ...
};

```

--------------------------------

### Using the @see Tag in JSDoc

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-see.md

Demonstrates how to use the @see tag to link to other functions or external resources. Use {@link} for inline links within descriptions.

```js
/**
 * Both of these will link to the bar function.
 * @see {@link bar}
 * @see bar
 */
function foo() {}

// Use the inline {@link} tag to include a link within a free-form description.
/**
 * @see {@link foo} for further information.
 * @see {@link http://github.com|GitHub}
 */
function bar() {}
```

--------------------------------

### Documenting a Global Callback with JSDoc

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-callback.md

Use this pattern to document a callback function that is globally available. The callback's name is not prefixed with a class namepath.

```javascript
/**
 * @class
 */
function Requester() {}

/**
 * Send a request.
 * @param {requestCallback} cb - The callback that handles the response.
 */
Requester.prototype.send = function(cb) {
    // code
};

/**
 * This callback is displayed as a global member.
 * @callback requestCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */
```

--------------------------------

### Documenting methods added to built-in classes with @external

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-external.md

Use the @external tag to document built-in JavaScript objects like `String`. This example shows how to document a custom method `rot13` added to the `String` prototype.

```js
/**
 * The built in string object.
 * @external String
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String|String}
 */

/**
 * Create a ROT13-encoded version of the string. Added by the `foo` package.
 * @function external:String#rot13
 * @example
 * var greeting = new String('hello world');
 * console.log( greeting.rot13() ); // uryyb jbeyq
 */
```

--------------------------------

### JSDoc @param: Name, type, and description

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-param.md

Provide a description for the parameter to explain its purpose.

```javascript
/**
 * @param {string} somebody Somebody's name.
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}
```

--------------------------------

### Define longname in @alias tag for local variables

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/howto-commonjs-modules.md

To document a symbol assigned to a local variable before export, use an `@alias` tag to define its correct longname. This example sets the longname for the `wash` method to `module:my/shirt.wash`.

```javascript
/**
 * Shirt module.
 * @module my/shirt
 */

/**
 * Wash the shirt.
 * @alias module:my/shirt.wash
 */
var wash = exports.wash = function() {
    // ...
};
```

--------------------------------

### Documenting a Constructor with @lends and @constructs

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/tags-lends.md

When using @lends to document instance methods, add the @constructs tag to the loaned function if it is responsible for constructing instances. Remove the @class tag from the outer scope to avoid documenting two classes.

```javascript
var Person = makeClass(
    /** @lends Person.prototype */
    {
        /**
         * Create a `Person` instance.
         * @constructs
         * @param {string} name - The person's name.
         */
        initialize: function(name) {
            this.name = name;
        },
        /**
         * Say something.
         * @param {string} message - The message to say.
         * @returns {string} The complete message.
         */
        say: function(message) {
            return this.name + " says: " + message;
        }
    }
);

```

--------------------------------

### Add Parameter Information with JSDoc Tags

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/about-getting-started.md

Document function parameters using tags like @param, specifying the type, name, and a description for each parameter.

```javascript
/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
}
```

--------------------------------

### Method assigned to a local variable and added to exports

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/howto-commonjs-modules.md

When an exported symbol is assigned to a local variable before being added to `exports`, JSDoc may not automatically document it. This example shows a `wash` method assigned to a local variable and then to `exports.wash`.

```javascript
/**
 * Shirt module.
 * @module my/shirt
 */

/** Wash the shirt. */
var wash = exports.wash = function() {
    // ...
};
```

--------------------------------

### Enable the Markdown plugin

Source: https://github.com/jsdoc/jsdoc.github.io/blob/main/content/plugins-markdown.md

To enable the Markdown plugin, add 'plugins/markdown' to the 'plugins' array in your JSDoc configuration file.

```json
{
    "plugins": ["plugins/markdown"]
}
```