

JSDoc
=====

 Getting Started
---------------

  [Getting Started with JSDoc 3](about-getting-started) A quick-start to documenting JavaScript with JSDoc. [Using namepaths with JSDoc 3](about-namepaths) A guide to using namepaths with JSDoc 3. [Command-line arguments to JSDoc](about-commandline) About command-line arguments to JSDoc. [Configuring JSDoc with a configuration file](about-configuring-jsdoc) How to configure JSDoc using a configuration file. [Configuring JSDoc's default template](about-configuring-default-template) How to configure the output from JSDoc's default template. [Block and inline tags](about-block-inline-tags) Overview of block and inline JSDoc tags. [About JSDoc plugins](about-plugins) How to create and use JSDoc plugins. [Using the Markdown plugin](plugins-markdown) Enable Markdown support in JSDoc. [Tutorials](about-tutorials) Adding tutorials to your API documentation. [Including a Package File](about-including-package) How to show package details in your documentation. [Including a README File](about-including-readme) How to include a README file in your documentation. [License](https://jsdoc.app/about-license-jsdoc3.html) License information for JSDoc 3.  JSDoc Examples
--------------

  [ES 2015 Classes](howto-es2015-classes) How to add JSDoc comments to ECMAScript 2015 classes. [ES 2015 Modules](howto-es2015-modules) How to add JSDoc comments to ECMAScript 2015 modules. [CommonJS Modules](howto-commonjs-modules) How to add JSDoc comments to CommonJS and Node.js modules. [AMD Modules](howto-amd-modules) How to add JSDoc comments to AMD and RequireJS modules.  Block Tags
----------

  
[@abstract](tags-abstract) (synonyms: @virtual) This member must be implemented (or overridden) by the inheritor. [@access](tags-access) Specify the access level of this member (private, package-private, public, or protected). [@alias](tags-alias) Treat a member as if it had a different name. [@async](tags-async) Indicate that a function is asynchronous. 
[@augments](tags-augments) (synonyms: @extends) Indicate that a symbol inherits from, and adds to, a parent symbol. [@author](tags-author) Identify the author of an item. [@borrows](tags-borrows) This object uses something from another object. [@callback](tags-callback) Document a callback function. 
[@class](tags-class) (synonyms: @constructor) This function is intended to be called with the "new" keyword. [@classdesc](tags-classdesc) Use the following text to describe the entire class. 
[@constant](tags-constant) (synonyms: @const) Document an object as a constant. [@constructs](tags-constructs) This function member will be the constructor for the previous class. [@copyright](tags-copyright) Document some copyright information. 
[@default](tags-default) (synonyms: @defaultvalue) Document the default value. [@deprecated](tags-deprecated) Document that this is no longer the preferred way. 
[@description](tags-description) (synonyms: @desc) Describe a symbol. [@enum](tags-enum) Document a collection of related properties. [@event](tags-event) Document an event. [@example](tags-example) Provide an example of how to use a documented item. [@exports](tags-exports) Identify the member that is exported by a JavaScript module. 
[@external](tags-external) (synonyms: @host) Identifies an external class, namespace, or module. 
[@file](tags-file) (synonyms: @fileoverview, @overview) Describe a file. 
[@fires](tags-fires) (synonyms: @emits) Describe the events this method may fire. 
[@function](tags-function) (synonyms: @func, @method) Describe a function or method. [@generator](tags-generator) Indicate that a function is a generator function. [@global](tags-global) Document a global object. [@hideconstructor](tags-hideconstructor) Indicate that the constructor should not be displayed. [@ignore](tags-ignore) Omit a symbol from the documentation. [@implements](tags-implements) This symbol implements an interface. [@inheritdoc](tags-inheritdoc) Indicate that a symbol should inherit its parent's documentation. [@inner](tags-inner) Document an inner object. [@instance](tags-instance) Document an instance member. [@interface](tags-interface) This symbol is an interface that others can implement. [@kind](tags-kind) What kind of symbol is this? [@lends](tags-lends) Document properties on an object literal as if they belonged to a symbol with a given name. [@license](tags-license) Identify the license that applies to this code. [@listens](tags-listens) List the events that a symbol listens for. 
[@member](tags-member) (synonyms: @var) Document a member. [@memberof](tags-memberof) This symbol belongs to a parent symbol. [@mixes](tags-mixes) This object mixes in all the members from another object. [@mixin](tags-mixin) Document a mixin object. [@module](tags-module) Document a JavaScript module. [@name](tags-name) Document the name of an object. [@namespace](tags-namespace) Document a namespace object. [@override](tags-override) Indicate that a symbol overrides its parent. [@package](tags-package) This symbol is meant to be package-private. 
[@param](tags-param) (synonyms: @arg, @argument) Document the parameter to a function. [@private](tags-private) This symbol is meant to be private. 
[@property](tags-property) (synonyms: @prop) Document a property of an object. [@protected](tags-protected) This symbol is meant to be protected. [@public](tags-public) This symbol is meant to be public. [@readonly](tags-readonly) This symbol is meant to be read-only. [@requires](tags-requires) This file requires a JavaScript module. 
[@returns](tags-returns) (synonyms: @return) Document the return value of a function. [@see](tags-see) Refer to some other documentation for more information. [@since](tags-since) When was this feature added? [@static](tags-static) Document a static member. [@summary](tags-summary) A shorter version of the full description. [@this](tags-this) What does the 'this' keyword refer to here? 
[@throws](tags-throws) (synonyms: @exception) Describe what errors could be thrown. [@todo](tags-todo) Document tasks to be completed. [@tutorial](tags-tutorial) Insert a link to an included tutorial file. [@type](tags-type) Document the type of an object. [@typedef](tags-typedef) Document a custom type. [@variation](tags-variation) Distinguish different objects with the same name. [@version](tags-version) Documents the version number of an item. 
[@yields](tags-yields) (synonyms: @yield) Document the value yielded by a generator function.  Inline Tags
-----------

  
[{@link}](tags-inline-link) (synonyms: {@linkcode}, {@linkplain}) Link to another item in the documentation. [{@tutorial}](tags-inline-tutorial) Link to a tutorial.  Contribute
----------

  [JSDoc project on GitHub](https://github.com/jsdoc3/jsdoc) Contribute to JSDoc. [Use JSDoc project on GitHub](https://github.com/jsdoc3/jsdoc3.github.com) Contribute to the JSDoc documentation.   [Fork me on GitHub](https://github.com/jsdoc3/jsdoc) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/index.html>

Getting Started with JSDoc 3
============================

 Table of Contents
-----------------

 * [Getting started](#getting-started)
* [Adding documentation comments to your code](#adding-documentation-comments-to-your-code)
* [Generating a website](#generating-a-website)

 Getting started
---------------

 JSDoc 3 is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor. You add documentation comments directly to your source code, right alongside the code itself. The JSDoc tool will scan your source code and generate an HTML documentation website for you.

 Adding documentation comments to your code
------------------------------------------

 JSDoc's purpose is to document the API of your JavaScript application or library. It is assumed that you will want to document things like modules, namespaces, classes, methods, method parameters, and so on.

 JSDoc comments should generally be placed immediately before the code being documented. Each comment must start with a `/**` sequence in order to be recognized by the JSDoc parser. Comments beginning with `/*`, `/***`, or more than 3 stars will be ignored. This is a feature to allow you to suppress parsing of comment blocks.

 The simplest documentation is just a description 
```
/** This is a description of the foo function. */
function foo() {
}

```
 Adding a description is simple—just type the description you want in the documentation comment.

 Special "JSDoc tags" can be used to give more information. For example, if the function is a constructor for a class, you can indicate this by adding a `@constructor` tag.

 Use a JSDoc tag to describe your code 
```
/**
 * Represents a book.
 * @constructor
 */
function Book(title, author) {
}

```
 More tags can be used to add more information. See the [home page](index#block-tags) for a complete list of tags that are recognized by JSDoc 3.

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

```
 Generating a website
--------------------

 Once your code is commented, you can use the JSDoc 3 tool to generate an HTML website from your source files.

 By default, JSDoc uses the built-in "default" template to turn the documentation into HTML. You can edit this template to suit your own needs or create an entirely new template if that is what you prefer.

 Running the documentation generator on the command line 
```
jsdoc book.js

```
 This command will create a directory named `out/` in the current working directory. Within that directory, you will find the generated HTML pages.



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/about-getting-started.html>

Configuring JSDoc's default template
====================================

 Table of Contents
-----------------

 * [Generating pretty-printed source files](#generating-pretty-printed-source-files)
* [Copying static files to the output directory](#copying-static-files-to-the-output-directory)
* [Showing the current date in the page footer](#showing-the-current-date-in-the-page-footer)
* [Showing longnames in the navigation column](#showing-longnames-in-the-navigation-column)
* [Overriding the default template's layout file](#overriding-the-default-templates-layout-file)
* [Related Links](#related-links)

 JSDoc's default template provides several options that you can use to customize the appearance and content of generated documentation.

 To use these options, you must [create a configuration file](about-configuring-jsdoc) for JSDoc and set the appropriate options in the configuration file.

 Generating pretty-printed source files
--------------------------------------

 By default, JSDoc's default template generates pretty-printed versions of your source files. It also links to these pretty-printed files in the documentation.

 To disable pretty-printed files, set the option `templates.default.outputSourceFiles` to `false`. Using this option also removes links to your source files from the documentation. This option is available in JSDoc 3.3.0 and later.

 Copying static files to the output directory
--------------------------------------------

 JSDoc's default template automatically copies a few static files, such as CSS stylesheets, to the output directory. In JSDoc 3.3.0 and later, you can tell the default template to copy additional static files to the output directory. For example, you might want to copy a directory of images to the output directory so you can display these images in your documentation.

 To copy additional static files to the output directory, use the following options:

 * `templates.default.staticFiles.include`: An array of paths whose contents should be copied to the output directory. Subdirectories will be copied as well.
* `templates.default.staticFiles.exclude`: An array of paths that should *not* be copied to the output directory.
* `templates.default.staticFiles.includePattern`: A regular expression indicating which files to copy. If this property is not defined, all files will be copied.
* `templates.default.staticFiles.excludePattern`: A regular expression indicating which files to skip. If this property is not defined, nothing will be skipped.

 Copying a directory of images to the output directory To copy all of the static files in `./myproject/static` to the output directory:

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

```
 If your static files directory contains the file `./myproject/static/img/screen.png`, you can display the image in your docs by using the HTML tag `<img src="img/screen.png">`.

 Showing the current date in the page footer
-------------------------------------------

 By default, JSDoc's default template always shows the current date in the footer of the generated documentation. In JSDoc 3.3.0 and later, you can omit the current date by setting the option `templates.default.includeDate` to `false`.

 Showing longnames in the navigation column
------------------------------------------

 By default, JSDoc's default template shows a shortened version of each symbol's name in the navigation column. For example, the symbol `my.namespace.MyClass` would be displayed simply as `MyClass`. To show the complete longname instead, set the option `templates.default.useLongnameInNav` to `true`. This option is available in JSDoc 3.4.0 and later.

 Overriding the default template's layout file
---------------------------------------------

 The default template uses a file named `layout.tmpl` to specify the header and footer for each page in the generated documentation. In particular, this file defines which CSS and JavaScript files are loaded for each page. In JSDoc 3.3.0 and later, you can specify your own `layout.tmpl` file to use, which allows you to load your own custom CSS and JavaScript files in addition to, or instead of, the standard files.

 To use this feature, set the option `templates.default.layoutFile` to the path to your customized layout file. Relative paths are resolved against the current working directory; the path to the configuration file; and the JSDoc directory, in that order.

 Related Links
-------------

  [Configuring JSDoc with a configuration file](about-configuring-jsdoc) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/about-configuring-default-template.html>

Using the Markdown plugin
=========================

 Table of Contents
-----------------

 * [Overview](#overview)
* [Enabling the Markdown plugin](#enabling-the-markdown-plugin)
* [Converting Markdown in additional JSDoc tags](#converting-markdown-in-additional-jsdoc-tags)
* [Excluding the default tags from Markdown processing](#excluding-the-default-tags-from-markdown-processing)
* [Hard-wrapping text at line breaks](#hard-wrapping-text-at-line-breaks)
* [Adding ID attributes to headings](#adding-id-attributes-to-headings)

 Overview
--------

 JSDoc includes a Markdown plugin that automatically converts Markdown-formatted text to HTML. You can use this plugin with any JSDoc template. In JSDoc 3.2.2 and later, the Markdown plugin uses the [marked Markdown parser](https://github.com/chjj/marked).

 **Note**: When you enable the Markdown plugin, be sure to include a leading asterisk on each line of your JSDoc comments. If you omit the leading asterisks, JSDoc's parser may remove asterisks that are used for Markdown formatting.

  By default, JSDoc looks for Markdown-formatted text in the following JSDoc tags:

 * [`@author`](tags-author)
* [`@classdesc`](tags-classdesc)
* [`@description`](tags-description) (including untagged descriptions at the start of a JSDoc comment)
* [`@param`](tags-param)
* [`@property`](tags-property)
* [`@returns`](tags-returns)
* [`@see`](tags-see)
* [`@throws`](tags-throws)

 Enabling the Markdown plugin
----------------------------

 To enable the Markdown plugin, add the string `plugins/markdown` to the `plugins` array in your [JSDoc configuration file](about-configuring-jsdoc):

 JSON configuration file that enables the Markdown plugin 
```
{
    "plugins": ["plugins/markdown"]
}

```
 Converting Markdown in additional JSDoc tags
--------------------------------------------

 By default, the Markdown plugin only processes [specific JSDoc tags](#default-tags) for Markdown text. You can handle Markdown text in other tags by adding a `markdown.tags` property to your JSDoc configuration file. The `markdown.tags` property contains an array of the additional doclet properties that can contain Markdown text. (In most cases, the name of the doclet property is the same as the tag name. However, some tags are stored differently; for example, the `@param` tag is stored in a doclet's `params` property. If you're not sure how a tag's text is stored in a doclet, run JSDoc with the `-X/--explain` tag, which prints each doclet to the console.)

 For example, if the `foo` and `bar` tags accept values that are stored in a doclet's `foo` and `bar` properties, you could enable Markdown processing of these tags by adding the following settings to your JSDoc configuration file:

 Converting Markdown in 'foo' and 'bar' tags 
```
{
    "plugins": ["plugins/markdown"],
    "markdown": {
        "tags": ["foo", "bar"]
    }
}

```
 Excluding the default tags from Markdown processing
---------------------------------------------------

 To prevent the Markdown plugin from processing any of the [default JSDoc tags](#default-tags), add a `markdown.excludeTags` property to your JSDoc configuration file. The `markdown.excludeTags` property contains an array of the default tags that should not be processed for Markdown text.

 For example, to exclude the `author` tag from Markdown processing:

 Excluding the 'author' tag from Markdown processing 
```
{
    "plugins": ["plugins/markdown"],
    "markdown": {
        "excludeTags": ["author"]
    }
}

```
 Hard-wrapping text at line breaks
---------------------------------

 By default, the Markdown plugin does not hard-wrap text at line breaks. This is because it's normal for a JSDoc comment to be wrapped across multiple lines. If you prefer to hard-wrap text at line breaks, set your JSDoc configuration file's `markdown.hardwrap` property to `true`. This property is available in JSDoc 3.4.0 and later.

 Adding ID attributes to headings
--------------------------------

 By default, the Markdown plugin does not add an `id` attribute to each HTML heading. To automatically add `id` attributes based on the heading's text, set your JSDoc configuration file's `markdown.idInHeadings` property to `true`. This property is available in JSDoc 3.4.0 and later.



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/plugins-markdown.html>

Including a Package File
========================

 Package files contain information that can be useful for your project's documentation, such as the project's name and version number. JSDoc can automatically use information from your project's `package.json` file when it generates documentation. For example, the default template shows the project's name and version number in the documentation.

 There are two ways to incorporate a `package.json` file into your documentation:

 1. In the source paths to your JavaScript files, include the path to a `package.json` file. JSDoc will use the first `package.json` file that it finds in your source paths.
2. Run JSDoc with the `-P/--package` command-line option, specifying the path to your `package.json` file. This option is available in JSDoc 3.3.0 and later.

 The `-P/--package` command-line option takes precedence over your source paths. If you use the `-P/--package` command-line option, JSDoc will ignore any `package.json` files in your source paths.

 The `package.json` file must use [npm's package format](https://docs.npmjs.com/files/package.json).

 Examples
--------

 Including a package file in your source paths 
```
jsdoc path/to/js path/to/package/package.json

```
 Using the -P/--package option 
```
jsdoc --package path/to/package/package-docs.json path/to/js

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/about-including-package.html>

Including a README File
=======================

 There are two ways to incorporate a `README` file into your documentation:

 1. In the source paths to your JavaScript files, include the path to a Markdown file named `README.md`. JSDoc will use the first `README.md` file that it finds in your source paths.
2. Run JSDoc with the `-R/--readme` command-line option, specifying the path to your `README` file. This option is available in JSDoc 3.3.0 and later. The `README` file may have any name and extension, but it must be in Markdown format.

 The `-R/--readme` command-line option takes precedence over your source paths. If you use the `-R/--readme` command-line option, JSDoc will ignore any `README.md` files in your source paths.

 If you are using JSDoc's default template, the `README` file's contents will be rendered in HTML in the generated documentation's `index.html` file.

 Examples
--------

 Including a README file in your source paths 
```
jsdoc path/to/js path/to/readme/README.md

```
 Using the -R/--readme option 
```
jsdoc --readme path/to/readme/README path/to/js

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/about-including-readme.html>

ES 2015 Classes
===============

 Table of Contents
-----------------

 * [Documenting a simple class](#documenting-a-simple-class)
* [Extending classes](#extending-classes)
* [Related Links](#related-links)

 JSDoc 3 makes it easy to document classes that follow the [ECMAScript 2015 specification](http://www.ecma-international.org/ecma-262/6.0/#sec-class-definitions). You don't need to use tags such as `@class` and `@constructor` with ES 2015 classes—JSDoc automatically identifies classes and their constructors simply by parsing your code. ES 2015 classes are supported in JSDoc 3.4.0 and later.

 Documenting a simple class
--------------------------

 The following example shows how to document a simple class with a constructor, two instance methods, and one static method:

 Simple ES 2015 class 
```
/** 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) {
        // ...
    }
}

```
 You can also document classes that are defined in a class expression, which assigns the class to a variable or constant:

 ES 2015 class expression 
```
/** Class representing a point. */
const Point = class {
    // and so on
}

```
 Extending classes
-----------------

 When you use the `extends` keyword to extend an existing class, you also need to tell JSDoc which class you're extending. You do this with the [`@augments` (or `@extends`) tag](tags-augments).

 For example, to extend the `Point` class shown above:

 Extending an ES 2015 class 
```
/**
 * Class representing a dot.
 * @extends Point
 */
class Dot extends Point {
    /**
     * Create a dot.
     * @param {number} x - The x value.
     * @param {number} y - The y value.
     * @param {number} width - The width of the dot, in pixels.
     */
    constructor(x, y, width) {
        // ...
    }

    /**
     * Get the dot's width.
     * @return {number} The dot's width, in pixels.
     */
    getWidth() {
        // ...
    }
}

```
 Related Links
-------------

  [@augments](tags-augments) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/howto-es2015-classes.html>

@access
=======

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@access <package|private|protected|public>`

 Overview
--------

 The `@access` tag specifies the access level of a member. You can use the `@access` tag as a synonym for other tags:

 * `@access package` is the same as `@package`. This option is available in JSDoc 3.5.0 and later.
* `@access private` is the same as `@private`.
* `@access protected` is the same as `@protected`.
* `@access public` is the same as `@public`.

 Private members are not shown in the generated output unless JSDoc is run with the `-p/--private` command-line option. In JSDoc 3.3.0 and later, you can also use the [`-a/--access` command-line option](about-commandline) to change this behavior.

 Note that a doclet's *access level* is different from its *scope*. For example, if `Parent` has an inner variable named `child` that is documented as `@public`, the `child` variable will still be treated as an inner variable with the namepath `Parent~child`. In other words, the `child` variable will have an inner scope, even though the variable is public. To change a doclet's scope, use the [`@instance`](tags-instance), [`@static`](tags-static), and [`@global`](tags-global) tags.

 Examples
--------

 Using @access as a synonym for other tags 
```
/** @constructor */
function Thingy() {

    /** @access private */
    var foo = 0;

    /** @access protected */
    this._bar = 1;

    /** @access package */
    this.baz = 2;

    /** @access public */
    this.pez = 3;

}

// same as...

/** @constructor */
function OtherThingy() {

    /** @private */
    var foo = 0;

    /** @protected */
    this._bar = 1;

    /** @package */
    this.baz = 2;

    /** @public */
    this.pez = 3;

}

```
 Related Links
-------------

 * [@global](tags-global)
* [@instance](tags-instance)
* [@package](tags-package)
* [@private](tags-private)
* [@protected](tags-protected)
* [@public](tags-public)
* [@static](tags-static)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-access.html>

@author
=======

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@author <name> [<emailAddress>]`

 Overview
--------

 The @author tag identifies the author of an item. In JSDoc 3.2 and later, if the author's name is followed by an email address enclosed in angle brackets, the default template will convert the email address to a `mailto:` link.

 Examples
--------

 Documenting the author of an item 
```
/**
 * @author Jane Smith <jsmith@example.com>
 */
function MyClass() {}

```
 Related Links
-------------

 * [@file](tags-file)
* [@version](tags-version)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-author.html>

Using namepaths with JSDoc 3
============================

 Table of Contents
-----------------

 * [Namepaths in JSDoc 3](#namepaths-in-jsdoc-3)
* [Related Links](#related-links)

 Namepaths in JSDoc 3
--------------------

 When referring to a JavaScript variable that is elsewhere in your documentation, you must provide a unique identifier that maps to that variable. A namepath provides a way to do so and disambiguate between instance members, static members and inner variables.

 Basic Syntax Examples of Namepaths in JSDoc 3 
```
myFunction
MyConstructor
MyConstructor#instanceMember
MyConstructor.staticMember
MyConstructor~innerMember // note that JSDoc 2 uses a dash

```
 The example below shows: an *instance* method named "say," an *inner* function also named "say," and a *static* method also named "say." These are three distinct methods that all exist independently of one another.

 Use a documentation tag to describe your code. 
```
/** @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

```
 You would use three different namepath syntaxes to refer to the three different methods:

 Use a documentation tag to describe your code. 
```
Person#say  // the instance method named "say."
Person.say  // the static method named "say."
Person~say  // the inner method named "say."

```
 You might wonder why there is a syntax to refer to an inner method when that method isn't directly accessible from outside the function it is defined in. While that is true, and thus the "~" syntax is rarely used, it *is* possible to return a reference to an inner method from another method inside that container, so it is possible that some object elsewhere in your code might borrow an inner method.

 Note that if a constructor has an instance member that is also a constructor, you can simply chain the namepaths together to form a longer namepath:

 Use a documentation tag to describe your code. 
```
/** @constructor */
Person = function() {
    /** @constructor */
    this.Idea = function() {
        this.consider = function(){
            return "hmmm";
        }
    }
}

var p = new Person();
var i = new p.Idea();
i.consider();

```
 In this case, to refer to the method named "consider," you would use the following namepath: `Person#Idea#consider`

 This chaining can be used with any combination of the connecting symbols: `# . ~`

 Special cases: modules, externals and events. 
```
/** 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
 */

```
 There are some special cases with namepaths: [@module](tags-module) names are prefixed by "module:", [@external](tags-external) names are prefixed by "external:", and [@event](tags-event) names are prefixed by "event:".

 Namepaths of objects with special characters in the name. 
```
/** @namespace */
var chat = {
    /**
     * Refer to this by {@link chat."#channel"}.
     * @namespace
     */
    "#channel": {
        /**
         * Refer to this by {@link chat."#channel".open}.
         * @type {boolean}
         * @defaultvalue
         */
        open: true,
        /**
         * Internal quotes have to be escaped by backslash. This is
         * {@link chat."#channel"."say-\"hello\""}.
         */
        'say-"hello"': function (msg) {}
    }
};

/**
 * Now we define an event in our {@link chat."#channel"} namespace.
 * @event chat."#channel"."op:announce-motd"
 */

```
 Above is an example of a namespace with "unusual" characters in its member names (the hash character, dashes, even quotes). To refer to these you just need quote the names: chat."#channel", chat."#channel"."op:announce-motd", and so on. Internal quotes in names should be escaped with backslashes: chat."#channel"."say-"hello"".

 Related Links
-------------

 * [Block and inline tags](about-block-inline-tags)
* [{@link}](tags-inline-link)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/about-namepaths.html>

Command-line arguments to JSDoc
===============================

 Table of Contents
-----------------

 * [Examples](#examples)
* [Related Links](#related-links)

 At its most basic level, JSDoc is used like so:

 
```
/path/to/jsdoc yourSourceCodeFile.js anotherSourceCodeFile.js ...

```
 where `...` are paths to other files to generate documentation for.

 Additionally, one may provide the path to a [Markdown file](http://daringfireball.net/projects/markdown/) (ending in ".md") or a file named "README", and this will be added to the documentation on the front page. See [these instructions](about-including-readme).

 JSDoc supports a number of command-line options, many of which have both long and short forms. Alternatively, the command-line options may be [specified in a configuration file](about-configuring-jsdoc) given to JSDoc. The command-line options are:

 

| Option | Description |
| --- | --- |
| `-a <value>`, `--access <value>` | Only display symbols with the given `access` property: `private`, `protected`, `public`, or `undefined`, or `all` for all access levels. By default, all except `private` symbols are shown. |
| `-c <value>`, `--configure <value>` | The path to a JSDoc [configuration file](about-configuring-jsdoc). Defaults to `conf.json` or `conf.json.EXAMPLE` in the directory where JSDoc is installed. |
| `-d <value>`, `--destination <value>` | The path to the output folder for the generated documentation. For JSDoc's built-in Haruki template, use `console` to dump data to the console. Defaults to `./out`. |
| `--debug` | Log information that can help debug issues in JSDoc itself. |
| `-e <value>`, `--encoding <value>` | Assume this encoding when reading all source files. Defaults to `utf8`. |
| `-h`, `--help` | Display information about JSDoc's command-line options, then exit. |
| `--match <value>` | Only run tests whose names contain `value`. |
| `--nocolor` | When running tests, do not use color in the console output. On Windows, this option is enabled by default. |
| `-p`, `--private` | Include symbols marked with the [`@private` tag](tags-private) in the generated documentation. By default, private symbols are not included. |
| `-P`, `--package` | The `package.json` file that contains the project name, version, and other details. Defaults to the first `package.json` file found in the source paths. |
| `--pedantic` | Treat errors as fatal errors, and treat warnings as errors. Defaults to `false`. |
| `-q <value>`, `--query <value>` | A query string to parse and store in the global variable `env.opts.query`. Example: `foo=bar&baz=true`. |
| `-r`, `--recurse` | Recurse into subdirectories when scanning for source files and tutorials. |
| `-R`, `--readme` | The `README.md` file to include in the generated documentation. Defaults to the first `README.md` file found in the source paths. |
| `-t <value>`, `--template <value>` | The path to the template to use for generating output. Defaults to `templates/default`, JSDoc's built-in default template. |
| `-T`, `--test` | Run JSDoc's test suite, and print the results to the console. |
| `-u <value>`, `--tutorials <value>` | Directory in which JSDoc should search for tutorials. If omitted, no tutorial pages will be generated. See the [tutorial instructions](about-tutorials) for more information. |
| `-v`, `--version` | Displays JSDoc's version number, then exits. |
| `--verbose` | Log detailed information to the console as JSDoc runs. Defaults to `false`. |
| `-X`, `--explain` | Dump all doclets to the console in JSON format, then exit. |

 Examples
--------

 Generate documentation for files in the `./src` directory, using the configuration file `/path/to/my/conf.json`, and save the output in the `./docs` directory:

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

```
 Run all JSDoc tests whose names include the word `tag`, and log information about each test:

 
```
/path/to/jsdoc -T --match tag --verbose

```
 Related Links
-------------

  [Configuring JSDoc with a configuration file](about-configuring-jsdoc) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/about-commandline.html>

Configuring JSDoc with a configuration file
===========================================

 Table of Contents
-----------------

 * [Configuration file formats](#configuration-file-formats)
* [Default configuration options](#default-configuration-options)
* [Configuring plugins](#configuring-plugins)
* [Specifying recursion depth](#specifying-recursion-depth)
* [Specifying input files](#specifying-input-files)
* [Specifying the source type](#specifying-the-source-type)
* [Incorporating command-line options into the configuration file](#incorporating-command-line-options-into-the-configuration-file)
* [Configuring tags and tag dictionaries](#configuring-tags-and-tag-dictionaries)
* [Configuring templates](#configuring-templates)
* [Related Links](#related-links)

 Configuration file formats
--------------------------

 To customize JSDoc's behavior, you can provide a configuration file to JSDoc in one of the following formats:

 * A JSON file. In JSDoc 3.3.0 and later, this file may include comments.
* A CommonJS module that exports a single configuration object. This format is supported in JSDoc

 3.5.0 and later.

 To run JSDoc with a configuration file, use the [`-c` command-line option](about-commandline) (for example, `jsdoc -c /path/to/conf.json` or `jsdoc -c /path/to/conf.js`).

 The following examples show a simple configuration file that enables JSDoc's [Markdown plugin](plugins-markdown). JSDoc's configuration options are explained in detail in the following sections.

 JSON configuration file 
```
{
    "plugins": ["plugins/markdown"]
}

```
 JavaScript configuration file 
```
'use strict';

module.exports = {
    plugins: ['plugins/markdown']
};

```
 For a more comprehensive example of a JSON configuration file, see the file [`conf.json.EXAMPLE`](https://github.com/jsdoc3/jsdoc/blob/master/conf.json.EXAMPLE).

 Default configuration options
-----------------------------

 If you do not specify a configuration file, JSDoc uses the following configuration options:

 
```
{
    "plugins": [],
    "recurseDepth": 10,
    "source": {
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "sourceType": "module",
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

```
 This means:

 * No plugins are loaded (`plugins`).
* If recursion is enabled with the [`-r` command-line flag](about-commandline), JSDoc will search for files 10 levels deep (`recurseDepth`).
* Only files ending in `.js`, `.jsdoc`, and `.jsx` will be processed (`source.includePattern`).
* Any file starting with an underscore, or in a directory starting with an underscore, will be ignored (`source.excludePattern`).
* JSDoc supports code that uses [ES2015 modules](howto-es2015-modules) (`sourceType`).
* JSDoc allows you to use unrecognized tags (`tags.allowUnknownTags`).
* Both standard JSDoc tags and [Closure Compiler tags](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#jsdoc-tags) are enabled (`tags.dictionaries`).
* [Inline `{@link}` tags](tags-inline-link) are rendered in plain text (`templates.cleverLinks`, `templates.monospaceLinks`).

 These options and others are explained in the following sections.

 Configuring plugins
-------------------

 To enable plugins, add their paths (relative to the JSDoc folder) into the `plugins` array.

 For example, the following JSON configuration file will enable the Markdown plugin, which converts Markdown-formatted text to HTML, and the "summarize" plugin, which autogenerates a summary for each doclet:

 JSON configuration file with plugins 
```
{
    "plugins": [
        "plugins/markdown",
        "plugins/summarize"
    ]
}

```
 See the [plugin reference](about-plugins) for further information, and look in [JSDoc's `plugins` directory](https://github.com/jsdoc3/jsdoc/tree/master/plugins) for the plugins built into JSDoc.

 You can configure the Markdown plugin by adding a `markdown` object to your configuration file. See [Configuring the Markdown Plugin](plugins-markdown) for details.

 Specifying recursion depth
--------------------------

 The `recurseDepth` option controls how many levels deep JSDoc will recursively search for source files and tutorials. This option is available in JSDoc 3.5.0 and later. This option is used only if you also specify the [`-r` command-line flag](about-commandline), which tells JSDoc to recursively search for input files.

 
```
{
    "recurseDepth": 10
}

```
 Specifying input files
----------------------

 The `source` set of options, in combination with paths given to JSDoc on the command line, determines the set of input files that JSDoc uses to generate documentation.

 
```
{
    "source": {
        "include": [ /* array of paths to files to generate documentation for */ ],
        "exclude": [ /* array of paths to exclude */ ],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    }
}

```
 * `source.include`: An optional array of paths that contain files for which JSDoc should generate documentation. The paths given to JSDoc on the command line are combined with these paths. You can use the [`-r` command-line option](about-commandline) to recurse into subdirectories.
* `source.exclude`: An optional array of paths that JSDoc should ignore. In JSDoc 3.3.0 and later, this array may include subdirectories of the paths in `source.include`.
* `source.includePattern`: An optional string, interpreted as a regular expression. If present, all filenames must match this regular expression to be processed by JSDoc. By default, this option is set to ".+\.js(doc|x)?$", meaning that only files with the extensions `.js`, `.jsdoc`, and `.jsx` will be processed.
* `source.excludePattern`: An optional string, interpreted as a regular expression. If present, any file matching this regular expression will be ignored. By default, this option is set so that files beginning with an underscore (or anything under a directory beginning with an underscore) is ignored.

 These options are interpreted in the following order:

 1. Start with all paths given on the command line and in `source.include`.
2. For each file found in Step 1, if the regular expression `source.includePattern` is present, the filename must match it, or it is ignored.
3. For each file left from Step 2, if the regular expression `source.excludePattern` is present, any filename matching this regular expression is ignored.
4. For each file left from Step 3, if the file's path is in `source.exclude`, it is ignored.

 All remaining files after these four steps are processed by JSDoc.

 As an example, suppose you have the following file structure:

 
```
myProject/
|- a.js
|- b.js
|- c.js
|- _private
|  |- a.js
|- lib/
   |- a.js
   |- ignore.js
   |- d.txt

```
 In addition, suppose your `conf.json` file looks like this example:

 
```
{
    "source": {
        "include": ["myProject/a.js", "myProject/lib", "myProject/_private"],
        "exclude": ["myProject/lib/ignore.js"],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    }
}

```
 If you run `jsdoc myProject/c.js -c /path/to/my/conf.json -r` from the file containing the `myProject` folder, JSDoc will generate documentation for the following files:

 * `myProject/a.js`
* `myProject/c.js`
* `myProject/lib/a.js`

 Here's why:

 1. Given `source.include` and the paths given on the command line, JSDoc starts off with these files:
	* `myProject/c.js` (from the command line)
	* `myProject/a.js` (from `source.include`)
	* `myProject/lib/a.js`, `myProject/lib/ignore.js`, `myProject/lib/d.txt` (from `source.include` and using the `-r` option)
	* `myProject/_private/a.js` (from `source.include`)
2. JSDoc applies `source.includePattern`, leaving us with all of the above files *except* `myProject/lib/d.txt`, which does not end in `.js`, `.jsdoc`, or `.jsx`.
3. JSDoc applies `source.excludePattern`, which removes `myProject/_private/a.js`.
4. JSDoc applies `source.exclude`, which removes `myProject/lib/ignore.js`.

 Specifying the source type
--------------------------

 The `sourceType` option affects how JSDoc parses your JavaScript files. This option is available in JSDoc 3.5.0 and later. This option accepts the following values:

 * `module` (default): Use this value for most types of JavaScript files.
* `script`: Use this value if JSDoc logs errors such as `Delete of an unqualified identifier in
 strict mode` when it parses your code.

 
```
{
    "sourceType": "module"
}

```
 Incorporating command-line options into the configuration file
--------------------------------------------------------------

 You can put many of JSDoc's [command-line options](about-commandline) into the configuration file instead of specifying them on the command line. To do this, add the long names of the relevant options into an `opts` section of the configuration file, with the value set to the option's value.

 JSON configuration file with command-line options 
```
{
    "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
    }
}

```
 By using the `source.include` and `opts` options, you can put almost all of the arguments to JSDoc in a configuration file, so that the command line reduces to:

 
```
jsdoc -c /path/to/conf.json

```
 When options are specified on the command line *and* in the configuration file, the command line takes precedence.

 Configuring tags and tag dictionaries
-------------------------------------

 The options in `tags` control which JSDoc tags are allowed and how each tag is interpreted.

 
```
{
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    }
}

```
 The `tags.allowUnknownTags` property affects how JSDoc handles unrecognized tags. If you set this option to `false`, and JSDoc finds a tag that it does not recognize (for example, `@foo`), JSDoc logs a warning. By default, this option is set to `true`. In JSDoc 3.4.1 and later, you can also set this property to an array of tag names that JSDoc should allow (for example, `["foo","bar"]`).

 The `tags.dictionaries` property controls which tags JSDoc recognizes, as well as how JSDoc interprets the tags that it recognizes. In JSDoc 3.3.0 and later, there are two built-in tag dictionaries:

 * `jsdoc`: Core JSDoc tags.
* `closure`: [Closure Compiler tags](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#jsdoc-tags).

 By default, both dictionaries are enabled. Also, by default, the `jsdoc` dictionary is listed first; as a result, if the `jsdoc` dictionary handles a tag differently than the `closure` dictionary, the `jsdoc` version of the tag takes precedence.

 If you are using JSDoc with a Closure Compiler project, and you want to avoid using tags that Closure Compiler does not recognize, change the `tags.dictionaries` setting to `["closure"]`. You can also change this setting to `["closure","jsdoc"]` if you want to allow core JSDoc tags, but you want to ensure that Closure Compiler-specific tags are interpreted as Closure Compiler would interpret them.

 Configuring templates
---------------------

 The options in `templates` affect the appearance and content of generated documentation. Third-party templates may not implement all of these options. See [Configuring JSDoc's Default Template](about-configuring-default-template) for additional options that the default template supports.

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

```
 If `templates.monospaceLinks` is true, all link text from the [inline `{@link}` tag](tags-inline-link) will be rendered in monospace.

 If `templates.cleverLinks` is true, `{@link asdf}` will be rendered in normal font if `asdf` is a URL, and monospace otherwise. For example, `{@link http://github.com}` will render in plain text, but `{@link MyNamespace.myFunction}` will be in monospace.

 If `templates.cleverLinks` is true, `templates.monospaceLinks` is ignored.

 Related Links
-------------

 * [Command-line arguments to JSDoc](about-commandline)
* [About JSDoc plugins](about-plugins)
* [Using the Markdown plugin](plugins-markdown)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/about-configuring-jsdoc.html>

Block and inline tags
=====================

 Table of Contents
-----------------

 * [Overview](#overview)
* [Examples](#examples)

 Overview
--------

 JSDoc supports two different kinds of tags:

 * **Block tags**, which are at the top level of a JSDoc comment.
* **Inline tags**, which are within the text of a block tag or a description.

 Block tags usually provide detailed information about your code, such as the parameters that a function accepts. Inline tags usually link to other parts of the documentation, similar to the anchor tag (`<a>`) in HTML.

 Block tags always begin with an at sign (`@`). Each block tag must be followed by a line break, with the exception of the last block tag in a JSDoc comment.

 Inline tags also begin with an at sign. However, inline tags and their text must be enclosed in curly braces (`{` and `}`). The `{` denotes the start of the inline tag, and the `}` denotes the end of the inline tag. If your tag's text includes a closing curly brace (`}`), you must escape it with a leading backslash (`\`). You do not need to use a line break after inline tags.

 Most JSDoc tags are block tags. In general, when this site refers to "JSDoc tags," we really mean "block tags."

 Examples
--------

 In the following example, `@param` is a block tag, and `{@link}` is an inline tag:

 Block and inline tags in JSDoc comments 
```
/**
 * Set the shoe's color. Use {@link Shoe#setSize} to set the shoe size.
 *
 * @param {string} color - The shoe's color.
 */
Shoe.prototype.setColor = function(color) {
    // ...
};

```
 You can use inline tags within a description, as shown above, or within a block tag, as shown below:

 Inline tag used within a block tag 
```
/**
 * Set the shoe's color.
 *
 * @param {SHOE_COLORS} color - The shoe color. Must be an enumerated
 * value of {@link SHOE_COLORS}.
 */
Shoe.prototype.setColor = function(color) {
    // ...
};

```
 When you use multiple block tags in a JSDoc comment, they must be separated by line breaks:

 Multiple block tags separated by line breaks 
```
/**
 * 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) {
    // ...
};

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/about-block-inline-tags.html>

About JSDoc plugins
===================

 Table of Contents
-----------------

 * [Creating and Enabling a Plugin](#creating-and-enabling-a-plugin)
* [Authoring JSDoc 3 Plugins](#authoring-jsdoc-3-plugins)
	+ [Event Handlers](#event-handlers)
	+ [Tag Definitions](#tag-definitions)
	+ [Node Visitors](#node-visitors)
* [Reporting Errors](#reporting-errors)

 Creating and Enabling a Plugin
------------------------------

 There are two steps required to create and enable a new JSDoc plugin:

 1. Create a JavaScript module to contain your plugin code.
2. Include that module in the `plugins` array of [JSDoc's configuration file](about-configuring-jsdoc). You can specify an absolute or relative path. If you use a relative path, JSDoc searches for the plugin in the current working directory; the directory where the configuration file is located; and the JSDoc directory, in that order.

 For example, if your plugin is defined in the `plugins/shout.js` file in the current working directory, you would add the string `plugins/shout` to the `plugins` array in your JSDoc configuration file:

 Adding a plugin to JSDoc's configuration file 
```
{
    "plugins": ["plugins/shout"]
}

```
 JSDoc executes plugins in the order that they are listed in the configuration file.

 Authoring JSDoc 3 Plugins
-------------------------

 JSDoc 3's plugin system offers extensive control over the parsing process. A plugin can affect the parse results by doing any of the following:

 * Defining event handlers
* Defining tags
* Defining a visitor for abstract syntax tree nodes

 ### Event Handlers

 At the highest level, a plugin may register handlers for specific named events that JSDoc fires. JSDoc will pass an event object to the handler. Your plugin module should export a `handlers` object that contains your handler, like so:

 Event-handler plugin for 'newDoclet' events 
```
exports.handlers = {
    newDoclet: function(e) {
        // Do something when we see a new doclet
    }
};

```
 JSDoc fires events in the same order as the underlying code.

 An event-handler plugin can stop later plugins from running by setting a `stopPropagation` property on the event object (`e.stopPropagation = true`). A plugin can stop the event from firing by setting a `preventDefault` property (`e.preventDefault = true`).

 #### Event: parseBegin

 The `parseBegin` event is fired before JSDoc starts loading and parsing the source files. Your plugin can control which files JSDoc will parse by modifying the event's contents.

 **Note**: This event is fired in JSDoc 3.2 and later.

 The event object contains the following properties:

 * `sourcefiles`: An array of paths to source files that will be parsed.

 #### Event: fileBegin

 The `fileBegin` event is fired when the parser is about to parse a file. Your plugin can use this event to trigger per-file initialization if necessary.

 The event object contains the following properties:

 * `filename`: The name of the file.

 #### Event: beforeParse

 The `beforeParse` event is fired before parsing has begun. Plugins can use this method to modify the source code that will be parsed. For instance, your plugin could add a JSDoc comment, or it could remove preprocessing tags that are not valid JavaScript.

 The event object contains the following properties:

 * `filename`: The name of the file.
* `source`: The contents of the file.

 Below is an example that adds a virtual comment for a function to the source so that it will get parsed and added to the documentation. This might be done to document methods that will be available to users, but might not appear in the source code being documented, such as methods provided by an external superclass:

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

```
 #### Event: jsdocCommentFound

 The `jsdocCommentFound` event is fired whenever a JSDoc comment is found. The comment may or may not be associated with any code. You might use this event to modify the contents of a comment before it is processed.

 The event object contains the following properties:

 * `filename`: The name of the file.
* `comment`: The text of the JSDoc comment.
* `lineno`: The line number on which the comment was found.
* `columnno`: The column number on which the comment was found. Available in JSDoc 3.5.0 and later.

 #### Event: symbolFound

 The `symbolFound` event is fired when the parser comes across a symbol in the code that may need to be documented. For example, the parser fires a `symbolFound` event for each variable, function, and object literal in a source file.

 The event object contains the following properties:

 * `filename`: The name of the file.
* `comment`: The text of the comment associated with the symbol, if any.
* `id`: The unique ID of the symbol.
* `lineno`: The line number on which the symbol was found.
* `columnno`: The column number on which the symbol was found. Available in JSDoc 3.5.0 and later.
* `range`: An array containing the numeric index of the first and last characters in the source file that are associated with the symbol.
* `astnode`: The symbol's node from the abstract syntax tree.
* `code`: Object with detailed information about the code. This object usually contains `name`, `type`, and `node` properties. The object might also have `value`, `paramnames`, or `funcscope` properties depending on the symbol.

 #### Event: newDoclet

 The `newDoclet` event is the highest-level event. It is fired when a new doclet has been created. This means that a JSDoc comment or a symbol has been processed, and the actual doclet that will be passed to the template has been created.

 The event object contains the following properties:

 * `doclet`: The new doclet that was created.

 The doclet's properties can vary depending on the comment or symbol that the doclet represents. Some common properties you're likely to see include:

 * `comment`: The text of the JSDoc comment, or an empty string if the symbol is undocumented.
* `meta`: Object that describes how the doclet relates to the source file (for example, the location within the source file).
* `description`: A description of the symbol being documented.
* `kind`: The kind of symbol being documented (for example, `class` or `function`).
* `name`: The short name for the symbol (for example, `myMethod`).
* `longname`: The fully qualified name, including memberof info (for example, `MyClass#myMethod`).
* `memberof`: The module, namespace, or class that this symbol belongs to (for example, `MyClass`), or an empty string if the symbol does not have a parent.
* `scope`: The scope of the symbol within its parent (for example, `global`, `static`, `instance`, or `inner`).
* `undocumented`: Set to `true` if the symbol did not have a JSDoc comment.
* `defaultvalue`: The default value for a symbol.
* `type`: Object containing details about the symbol's type.
* `params`: Object containing the list of parameters to a function.
* `tags`: Object containing a list of tags that JSDoc did not recognize. Only available if `allowUnknownTags` is set to `true` in JSDoc's configuration file.

 To see the doclets that JSDoc generates for your code, run JSDoc with the [`-X` command-line option](about-commandline).

 Below is an example of a `newDoclet` handler that shouts the descriptions:

 Example 
```
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();
        }
    }
};

```
 #### Event: fileComplete

 The `fileComplete` event is fired when the parser has finished parsing a file. Your plugin could use this event to trigger per-file cleanup.

 The event object contains the following properties:

 * `filename`: The name of the file.
* `source`: The contents of the file.

 #### Event: parseComplete

 The `parseComplete` event is fired after JSDoc has parsed all of the specified source files.

 **Note**: This event is fired in JSDoc 3.2 and later.

 The event object contains the following properties:

 * `sourcefiles`: An array of paths to source files that were parsed.
* `doclets`: An array of doclet objects. See the [`newDoclet` event](#event-newdoclet) for details about the properties that each doclet can contain. Available in JSDoc 3.2.1 and later.

 #### Event: processingComplete

 The `processingComplete` event is fired after JSDoc updates the parse results to reflect inherited and borrowed symbols.

 **Note**: This event is fired in JSDoc 3.2.1 and later.

 The event object contains the following properties:

 * `doclets`: An array of doclet objects. See the [`newDoclet` event](#event-newdoclet) for details about the properties that each doclet can contain.

 ### Tag Definitions

 Adding tags to the tag dictionary is a mid-level way to affect documentation generation. Before a `newDoclet` event is triggered, JSDoc comment blocks are parsed to determine the description and any JSDoc tags that may be present. When a tag is found, if it has been defined in the tag dictionary, it is given a chance to modify the doclet.

 Plugins can define tags by exporting a `defineTags` function. That function will be passed a dictionary that can be used to define tags, like so:

 Example 
```
exports.defineTags = function(dictionary) {
    // define tags here
};

```
 #### The Dictionary

 The dictionary provides the following methods:

 * `defineTag(title, opts)`: Used to define tags. The first parameter is the name of the tag (for example, `param` or `overview`). The second is an object containing options for the tag. You can include any of the following options; the default value for each option is `false`:
	+ `canHaveType (boolean)`: Set to `true` if the tag text can include a type expression (such as `{string}` in `@param {string} name - Description`).
	+ `canHaveName (boolean)`: Set to `true` if the tag text can include a name (such as `name` in `@param {string} name - Description`).
	+ `isNamespace (boolean)`: Set to `true` if the tag should be applied to the doclet's longname as a namespace. For example, the `@module` tag sets this option to `true`, and using the tag `@module myModuleName` results in the longname `module:myModuleName`.
	+ `mustHaveValue (boolean)`: Set to `true` if the tag must have a value (such as `TheName` in `@name TheName`).
	+ `mustNotHaveDescription (boolean)`: Set to `true` if the tag may have a value but must not have a description (such as `TheDescription` in `@tag {typeExpr} TheDescription`).
	+ `mustNotHaveValue (boolean)`: Set to `true` if the tag must not have a value.
	+ `onTagged (function)`: A callback function executed when the tag is found. The function is passed two parameters: the doclet and the tag object.
* `lookUp(tagName)`: Retrieve a tag object by name. Returns the tag object, including its options, or `false` if the tag is not defined.
* `isNamespace(tagName)`: Returns `true` if the tag is applied to a doclet's longname as a namespace.
* `normalise(tagName)`: Returns the canonical name of a tag. For example, the `@const` tag is a synonym for `@constant`; as a result, if you call `normalise('const')`, it returns the string `constant`.
* `normalize(tagName)`: Synonym for `normalise`. Available in JSDoc 3.3.0 and later.

 A tag's `onTagged` callback can modify the contents of the doclet or tag.

 Defining an onTagged callback 
```
dictionary.defineTag('instance', {
    onTagged: function(doclet, tag) {
        doclet.scope = "instance";
    }
});

```
 The `defineTag` method returns a `Tag` object, which has a `synonym` method that can be used to declare a synonym for the tag.

 Defining a tag synonym 
```
dictionary.defineTag('exception', { /* options for exception tag */ })
    .synonym('throws');

```
 ### Node Visitors

 At the lowest level, plugin authors can process each node in the abstract syntax tree (AST) by defining a node visitor that will visit each node. By using a node-visitor plugin, you can modify comments and trigger parser events for any arbitrary piece of code.

 Plugins can define a node visitor by exporting an `astNodeVisitor` object that contains a `visitNode` function, like so:

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

```
 The function is called on each node with the following parameters:

 * `node`: The AST node. AST nodes are JavaScript objects that use the format defined by the [ESTree spec](https://github.com/estree/estree). You can use [AST Explorer](https://astexplorer.net/) to see the AST that will be created for your source code. As of version 3.5.0, JSDoc uses the current version of the [Babylon](https://github.com/babel/babylon) parser with all plugins enabled.
* `e`: The event. If the node is one that the parser handles, the event object will already be populated with the same things described in the `symbolFound` event above. Otherwise, it will be an empty object on which to set various properties.
* `parser`: The JSDoc parser instance.
* `currentSourceName`: The name of the file being parsed.

 #### Making things happen

 The primary reasons to implement a node visitor are to be able to document things that aren't normally documented (like function calls that create classes) or to auto generate documentation for code that isn't documented. For instance, a plugin might look for calls to a `_trigger` method since it knows that means an event is fired and then generate documentation for the event.

 To make things happen, the `visitNode` function should modify properties of the event parameter. In general the goal is to construct a comment and then get an event to fire. After the parser lets all of the node visitors have a look at the node, it looks to see if the event object has a `comment` property and an `event` property. If it has both, the event named in the event property is fired. The event is usually `symbolFound` or `jsdocCommentFound`, but theoretically, a plugin could define its own events and handle them.

 As with event-handler plugins, a node-visitor plugin can stop later plugins from running by setting a `stopPropagation` property on the event object (`e.stopPropagation = true`). A plugin can stop the event from firing by setting a `preventDefault` property (`e.preventDefault = true`).

 Reporting Errors
----------------

 If your plugin needs to report an error, use one of the following methods in the `jsdoc/util/logger` module:

 * `logger.warn`: Warn the user about a possible problem.
* `logger.error`: Report an error from which the plugin can recover.
* `logger.fatal`: Report an error that should cause JSDoc to stop running.

 Using these methods creates a better user experience than simply throwing an error.

 **Note**: Do not use the `jsdoc/util/error` module to report errors. This module is deprecated and will be removed in a future version of JSDoc.

 Reporting a non-fatal error 
```
var logger = require('jsdoc/util/logger');

exports.handlers = {
    newDoclet: function(e) {
        // Your code here.

        if (somethingBadHappened) {
            logger.error('Oh, no, something bad happened!');
        }
    }
};

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/about-plugins.html>

Tutorials
=========

 Table of Contents
-----------------

 * [Adding tutorials](#adding-tutorials)
* [Configuring titles, order, and hierarchy](#configuring-titles-order-and-hierarchy)
* [Linking to tutorials from API documentation](#linking-to-tutorials-from-api-documentation)
	+ [@tutorial block tag](#tutorial-block-tag)
	+ [{@tutorial} inline tag](#tutorial-inline-tag)

 JSDoc allows you to include tutorials alongside your API documentation. You can use this feature to provide detailed instructions for using your API, such as a "getting started" guide or a step-by-step process for implementing a feature.

 Adding tutorials
----------------

 To add tutorials to your API documentation, run JSDoc with the `--tutorials` or `-u` option, and provide a directory that JSDoc should search for tutorials. For example:

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

```
 JSDoc searches the tutorials directory for files with the following extensions:

 * `.htm`
* `.html`
* `.markdown` (converted from Markdown to HTML)
* `.md` (converted from Markdown to HTML)
* `.xhtml`
* `.xml` (treated as HTML)

 JSDoc also searches for JSON files that contain information about the titles, ordering, and hierarchy of your tutorials, as discussed in the following section.

 JSDoc assigns an identifier to each tutorial. The identifier is the filename without its extension. For example, the identifier for `/path/to/tutorials/overview.md` is `overview`.

 In tutorial files, you can use the [`{@link}`](tags-inline-link) and [`{@tutorial}`](tags-inline-tutorial) inline tags to link to other parts of the documentation. JSDoc will automatically resolve the links.

 Configuring titles, order, and hierarchy
----------------------------------------

 By default, JSDoc uses the filename as the tutorial's title, and all tutorials are at the same level. You can use a JSON file to provide a title for each tutorial and indicates how the tutorials should be sorted and grouped in the documentation.

 The JSON file must use the extension `.json`. In the JSON file, you can use the tutorial identifiers to provide two properties for each tutorial:

 * `title`: The title to display in the documentation.
* `children`: The children of the tutorial.

 In JSDoc 3.2.0 and later, you can use the following formats for the JSON file:

 1. A tree of objects, with child tutorials defined in the `children` property of their parent. For example, if `tutorial1` has two children, `childA` and `childB`, and `tutorial2` is at the same level as `tutorial1` and has no children:

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

```
2. A top-level object whose properties are all tutorial objects, with child tutorials listed by name in an array. For example, if `tutorial1` has two children, `childA` and `childB`, and `tutorial2` is at the same level as `tutorial1` and has no children:

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

```

 You can also provide an individual `.json` file for each tutorial, using the tutorial identifier as the filename. This method is deprecated and should not be used for new projects.

 Linking to tutorials from API documentation
-------------------------------------------

 There are multiple ways to link to a tutorial from your API documentation:

 ### @tutorial block tag

 If you include a [`@tutorial` block tag](tags-tutorial) in a JSDoc comment, the generated documentation will include a link to the tutorial you specify.

 Using the `@tutorial` block tag 
```
/**
 * Class representing a socket connection.
 *
 * @class
 * @tutorial socket-tutorial
 */
function Socket() {}

```
 ### {@tutorial} inline tag

 You can also use the [`{@tutorial}` inline tag](tags-inline-tutorial) to link to a tutorial within the text of another tag. By default, JSDoc will use the tutorial's title as the link text.

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

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/about-tutorials.html>

ES 2015 Modules
===============

 Table of Contents
-----------------

 * [Module identifiers](#module-identifiers)
* [Exported values](#exported-values)
* [Related Links](#related-links)

 JSDoc 3 makes it possible to document modules that follow the [ECMAScript 2015 specification](http://www.ecma-international.org/ecma-262/6.0/#sec-modules). ES 2015 modules are supported in JSDoc 3.4.0 and later.

 Module identifiers
------------------

 When you document an ES 2015 module, you'll use a [`@module` tag](tags-module) to document the identifier for the module. For example, if users load the module by calling `import * as myShirt
 from 'my/shirt'`, you'll write a JSDoc comment that contains the tag `@module my/shirt`.

 If you use the `@module` tag without a value, JSDoc will try to guess the correct module identifier based on the filepath.

 When you use a JSDoc [namepath](about-namepaths) to refer to a module from another JSDoc comment, you must add the prefix `module:`. For example, if you want the documentation for the module `my/pants` to link to the module `my/shirt`, you could use the [`@see` tag](tags-see) to document `my/pants` as follows:

 
```
/**
 * Pants module.
 * @module my/pants
 * @see module:my/shirt
 */

```
 Similarly, the namepath for each member of the module will start with `module:`, followed by the module name. For example, if your `my/pants` module exports a `Jeans` class, and `Jeans` has an instance method named `hem`, the instance method's longname is `module:my/pants.Jeans#hem`.

 Exported values
---------------

 The following example shows how to document different kinds of exported values in an ES 2015 module. In most cases, you can simply add a JSDoc comment to the `export` statement that defines the exported value. If you are exporting a value under another name, you can document the exported value within its `export` block.

 Documenting values exported by a module 
```
/** @module color/mixer */

/** The name of the module. */
export const name = 'mixer';

/** The most recent blended color. */
export var lastColor = null;

/**
 * Blend two colors together.
 * @param {string} color1 - The first color, in hexadecimal format.
 * @param {string} color2 - The second color, in hexadecimal format.
 * @return {string} The blended color.
 */
export function blend(color1, color2) {}

// convert color to array of RGB values (0-255)
function rgbify(color) {}

export {
    /**
     * Get the red, green, and blue values of a color.
     * @function
     * @param {string} color - A color, in hexadecimal format.
     * @returns {Array.<number>} An array of the red, green, and blue values,
     * each ranging from 0 to 255.
     */
    rgbify as toRgb
}

```
 Related Links
-------------

 * [Using namepaths with JSDoc 3](about-namepaths)
* [@module](tags-module)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/howto-es2015-modules.html>

CommonJS Modules
================

 Table of Contents
-----------------

 * [Overview](#overview)
* [Module identifiers](#module-identifiers)
* [Properties of the 'exports' object](#properties-of-the-exports-object)
* [Values assigned to local variables](#values-assigned-to-local-variables)
* [Values assigned to 'module.exports'](#values-assigned-to-moduleexports)
	+ [Object literal assigned to 'module.exports'](#object-literal-assigned-to-moduleexports)
	+ [Function assigned to 'module.exports'](#function-assigned-to-moduleexports)
	+ [String, number, or boolean assigned to 'module.exports'](#string-number-or-boolean-assigned-to-moduleexports)
* [Values assigned to 'module.exports' and local variables](#values-assigned-to-moduleexports-and-local-variables)
* [Properties added to 'this'](#properties-added-to-this)
* [Related Links](#related-links)

 Overview
--------

 To help you document [CommonJS modules](http://wiki.commonjs.org/wiki/Modules/1.1), JSDoc 3 understands many of the conventions used in the CommonJS specification (for example, adding properties to the `exports` object). In addition, JSDoc recognizes the conventions of [Node.js modules](http://nodejs.org/api/modules.html), which extend the CommonJS standard (for example, assigning a value to `module.exports`). Depending on the coding conventions you follow, you may need to provide some additional tags to help JSDoc understand your code.

 This page explains how to document CommonJS and Node.js modules that use several different coding conventions. If you're documenting Asynchronous Module Definition (AMD) modules (also known as "RequireJS modules"), see [AMD Modules](howto-amd-modules).

 Module identifiers
------------------

 In most cases, your CommonJS or Node.js module should include a standalone JSDoc comment that contains a [`@module` tag](tags-module). The `@module` tag's value should be the module identifier that's passed to the `require()` function. For example, if users load the module by calling `require('my/shirt')`, your JSDoc comment would contain the tag `@module my/shirt`.

 If you use the `@module` tag without a value, JSDoc will try to guess the correct module identifier based on the filepath.

 When you use a JSDoc [namepath](about-namepaths) to refer to a module from another JSDoc comment, you must add the prefix `module:`. For example, if you want the documentation for the module `my/pants` to link to the module `my/shirt`, you could use the [`@see` tag](tags-see) to document `my/pants` as follows:

 
```
/**
 * Pants module.
 * @module my/pants
 * @see module:my/shirt
 */

```
 Similarly, the namepath for each member of the module will start with `module:`, followed by the module name. For example, if your `my/pants` module exports a `Jeans` constructor, and `Jeans` has an instance method named `hem`, the instance method's longname is `module:my/pants.Jeans#hem`.

 Properties of the 'exports' object
----------------------------------

 It's easiest to document symbols that are directly assigned to a property of the `exports` object. JSDoc will automatically recognize that the module exports these symbols.

 In the following example, the `my/shirt` module exports the methods `button` and `unbutton`. JSDoc will automatically detect that the module exports these methods.

 Methods added to the exports object 
```
/**
 * Shirt module.
 * @module my/shirt
 */

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

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

```
 Values assigned to local variables
----------------------------------

 In some cases, an exported symbol may be assigned to a local variable before it's added to the `exports` object. For example, if your module exports a `wash` method, and the module itself often calls the `wash` method, you might write the module as follows:

 Method assigned to a local variable and added to the exports object 
```
/**
 * Shirt module.
 * @module my/shirt
 */

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

```
 In this case, JSDoc will *not* automatically document `wash` as an exported method, because the JSDoc comment appears immediately before the local variable `wash` rather than `exports.wash`. One solution is to add an [`@alias` tag](tags-alias) that defines the correct longname for the method. In this case, the method is a static member of the module `my/shirt`, so the correct longname is `module:my/shirt.wash`:

 Longname defined in an @alias tag 
```
/**
 * Shirt module.
 * @module my/shirt
 */

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

```
 Another solution is to move the method's JSDoc comment so it comes immediately before `exports.wash`. This change allows JSDoc to detect that `wash` is exported by the module `my/shirt`:

 JSDoc comment immediately before exports.wash 
```
/**
 * Shirt module.
 * @module my/shirt
 */

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

```
 Values assigned to 'module.exports'
-----------------------------------

 In a Node.js module, you can assign a value directly to `module.exports`. This section explains how to document different types of values when they are assigned to `module.exports`.

 ### Object literal assigned to 'module.exports'

 If a module assigns an object literal to `module.exports`. JSDoc automatically recognizes that the module exports only this value. In addition, JSDoc automatically sets the correct longname for each property:

 Object literal assigned to module.exports 
```
/**
 * Color mixer.
 * @module color/mixer
 */

module.exports = {
    /**
     * Blend two colors together.
     * @param {string} color1 - The first color, in hexadecimal format.
     * @param {string} color2 - The second color, in hexadecimal format.
     * @return {string} The blended color.
     */
    blend: function(color1, color2) {
        // ...
    },

    /**
     * Darken a color by the given percentage.
     * @param {string} color - The color, in hexadecimal format.
     * @param {number} percent - The percentage, ranging from 0 to 100.
     * @return {string} The darkened color.
     */
    darken: function(color, percent) {
        // ..
    }
};

```
 You can also use this pattern if you add properties to `module.exports` outside of the object literal:

 Assignment to module.exports followed by property definition 
```
/**
 * Color mixer.
 * @module color/mixer
 */

module.exports = {
    /**
     * Blend two colors together.
     * @param {string} color1 - The first color, in hexadecimal format.
     * @param {string} color2 - The second color, in hexadecimal format.
     * @return {string} The blended color.
     */
    blend: function(color1, color2) {
        // ...
    }
};

/**
 * Darken a color by the given percentage.
 * @param {string} color - The color, in hexadecimal format.
 * @param {number} percent - The percentage, ranging from 0 to 100.
 * @return {string} The darkened color.
 */
module.exports.darken = function(color, percent) {
    // ..
};

```
 ### Function assigned to 'module.exports'

 If you assign a function to `module.exports`, JSDoc will automatically set the correct longname for the function:

 Function assigned to 'module.exports' 
```
/**
 * Color mixer.
 * @module color/mixer
 */

/**
 * Blend two colors together.
 * @param {string} color1 - The first color, in hexadecimal format.
 * @param {string} color2 - The second color, in hexadecimal format.
 * @return {string} The blended color.
 */
module.exports = function(color1, color2) {
    // ...
};

```
 The same pattern works for constructor functions:

 Constructor assigned to 'module.exports' 
```
/**
 * Color mixer.
 * @module color/mixer
 */

/** Create a color mixer. */
module.exports = function ColorMixer() {
    // ...
};

```
 ### String, number, or boolean assigned to 'module.exports'

 For value types (strings, numbers, and booleans) assigned to `module.exports`, you must document the exported value's type by using the [`@type` tag](tags-type) in the same JSDoc comment as the `@module` tag:

 String assigned to module.exports 
```
/**
 * Module representing the word of the day.
 * @module wotd
 * @type {string}
 */

module.exports = 'perniciousness';

```
 Values assigned to 'module.exports' and local variables
-------------------------------------------------------

 If your module exports symbols that are not directly assigned to `module.exports`, you can use the [`@exports` tag](tags-exports) in place of the `@module` tag. The `@exports` tag tells JSDoc that a symbol represents the value exported by a module.

 Object literal assigned to a local variable and module.exports 
```
/**
 * Color mixer.
 * @exports color/mixer
 */
var mixer = module.exports = {
    /**
     * Blend two colors together.
     * @param {string} color1 - The first color, in hexadecimal format.
     * @param {string} color2 - The second color, in hexadecimal format.
     * @return {string} The blended color.
     */
    blend: function(color1, color2) {
        // ...
    }
};


```
 Properties added to 'this'
--------------------------

 When a module adds a property to its `this` object, JSDoc 3 automatically recognizes that the new property is exported by the module:

 Properties added to a module's 'this' object 
```
/**
 * Module for bookshelf-related utilities.
 * @module bookshelf
 */

/**
 * Create a new Book.
 * @class
 * @param {string} title - The title of the book.
 */
this.Book = function(title) {
    /** The title of the book. */
    this.title = title;
}

```
 Related Links
-------------

 * [Using namepaths with JSDoc 3](about-namepaths)
* [@exports](tags-exports)
* [@module](tags-module)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/howto-commonjs-modules.html>

AMD Modules
===========

 Table of Contents
-----------------

 * [Overview](#overview)
* [Module identifiers](#module-identifiers)
* [Function that returns an object literal](#function-that-returns-an-object-literal)
* [Function that returns another function](#function-that-returns-another-function)
* [Module declared in a return statement](#module-declared-in-a-return-statement)
* [Module object passed to a function](#module-object-passed-to-a-function)
* [Multiple modules defined in one file](#multiple-modules-defined-in-one-file)
* [Related Links](#related-links)

 Overview
--------

 JSDoc 3 makes it possible to document modules that use the [Asynchronous Module Definition (AMD) API](https://github.com/amdjs/amdjs-api/blob/master/AMD.md), which is implemented by libraries such as [RequireJS](http://requirejs.org/). This page explains how to document an AMD module for JSDoc, based on the coding conventions that your module uses.

 If you're documenting CommonJS or Node.js modules, see [CommonJS Modules](howto-commonjs-modules) for instructions.

 Module identifiers
------------------

 When you document an AMD module, you'll use an [`@exports` tag](tags-exports) or [`@module` tag](tags-module) to document the identifier that's passed to the `require()` function. For example, if users load the module by calling `require('my/shirt', /* callback */)`, you'll write a JSDoc comment that contains the tag `@exports my/shirt` or `@module my/shirt`. The examples below can help you decide which of these tags to use.

 If you use the `@exports` or `@module` tag without a value, JSDoc will try to guess the correct module identifier based on the filepath.

 When you use a JSDoc [namepath](about-namepaths) to refer to a module from another JSDoc comment, you must add the prefix `module:`. For example, if you want the documentation for the module `my/pants` to link to the module `my/shirt`, you could use the [`@see` tag](tags-see) to document `my/pants` as follows:

 
```
/**
 * Pants module.
 * @module my/pants
 * @see module:my/shirt
 */

```
 Similarly, the namepath for each member of the module will start with `module:`, followed by the module name. For example, if your `my/pants` module exports a `Jeans` constructor, and `Jeans` has an instance method named `hem`, the instance method's longname is `module:my/pants.Jeans#hem`.

 Function that returns an object literal
---------------------------------------

 If you define your AMD module as a function that returns an object literal, use the [`@exports` tag](tags-exports) to document the module's name. JSDoc will automatically detect that the object's properties are members of the module.

 Function that returns an object literal 
```
define('my/shirt', function() {
   /**
    * A module representing a shirt.
    * @exports my/shirt
    */
    var shirt = {
        /** The module's `color` property. */
        color: 'black',

        /**
         * Create a new Turtleneck.
         * @class
         * @param {string} size - The size (`XS`, `S`, `M`, `L`, `XL`, or `XXL`).
         */
        Turtleneck: function(size) {
            /** The class's `size` property. */
            this.size = size;
        }
    };

    return shirt;
});

```
 Function that returns another function
--------------------------------------

 If you define your module as a function that exports another function, such as a constructor, you can use a standalone comment with a [`@module` tag](tags-module) to document the module. You can then use an [`@alias` tag](tags-alias) to tell JSDoc that the function uses the same longname as the module.

 Function that returns a constructor 
```
/**
 * 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;
});

```
 Module declared in a return statement
-------------------------------------

 If you declare your module object in a function's `return` statement, you can use a standalone comment with a [`@module` tag](tags-module) to document the module. You can then add an [`@alias` tag](tags-alias) to tell JSDoc that the module object has the same longname as the module.

 Module declared in a return statement 
```
/**
 * Module representing a shirt.
 * @module my/shirt
 */

define('my/shirt', function() {
    // Do setup work here.

    return /** @alias module:my/shirt */ {
        /** Color. */
        color: 'black',
        /** Size. */
        size: 'unisize'
    };
});

```
 Module object passed to a function
----------------------------------

 If the module object is passed into the function that defines your module, you can document the module by adding an [`@exports` tag](tags-exports) to the function parameter. This pattern is supported in JSDoc 3.3.0 and later.

 Module object passed to a function 
```
define('my/jacket', function(
    /**
     * Utility functions for jackets.
     * @exports my/jacket
     */
    module) {

    /**
     * Zip up a jacket.
     * @param {Jacket} jacket - The jacket to zip up.
     */
    module.zip = function(jacket) {
        // ...
    };
});

```
 Multiple modules defined in one file
------------------------------------

 If you define more than one AMD module in a single JavaScript file, use the [`@exports` tag](tags-exports) to document each module object.

 Multiple AMD modules defined in one file 
```
// one module
define('html/utils', function() {
    /**
     * Utility functions to ease working with DOM elements.
     * @exports html/utils
     */
    var utils = {
        /**
         * Get the value of a property on an element.
         * @param {HTMLElement} element - The element.
         * @param {string} propertyName - The name of the property.
         * @return {*} The value of the property.
         */
        getStyleProperty: function(element, propertyName) { }
    };

    /**
     * Determine if an element is in the document head.
     * @param {HTMLElement} element - The element.
     * @return {boolean} Set to `true` if the element is in the document head,
     * `false` otherwise.
     */
    utils.isInHead = function(element) { }

    return utils;
    }
);

// another module
define('tag', function() {
    /** @exports tag */
    var tag = {
        /**
         * Create a new Tag.
         * @class
         * @param {string} tagName - The name of the tag.
         */
        Tag: function(tagName) {
            // ...
        }
    };

    return tag;
});

```
 Related Links
-------------

 * [Using namepaths with JSDoc 3](about-namepaths)
* [@exports](tags-exports)
* [@module](tags-module)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/howto-amd-modules.html>

@abstract
=========

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Overview](#overview)
* [Example](#example)

 Synonyms
--------

  `@virtual` 

 Overview
--------

 The @abstract tag identifies members that must be implemented (or overridden) by objects that inherit the member.

 Example
-------

 Parent class with abstract method, and child class that implements the method 
```
/**
 * Generic dairy product.
 * @constructor
 */
function DairyProduct() {}

/**
 * Check whether the dairy product is solid at room temperature.
 * @abstract
 * @return {boolean}
 */
DairyProduct.prototype.isSolid = function() {
    throw new Error('must be implemented by subclass!');
};

/**
 * Cool, refreshing milk.
 * @constructor
 * @augments DairyProduct
 */
function Milk() {}

/**
 * Check whether milk is solid at room temperature.
 * @return {boolean} Always returns false.
 */
Milk.prototype.isSolid = function() {
    return false;
};

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-abstract.html>

@alias
======

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@alias <aliasNamepath>`

 Overview
--------

 The @alias tag causes JSDoc to treat all references to a member as if the member had a different name. This tag is especially useful if you define a class within an inner function; in this case, you can use the @alias tag to tell JSDoc how the class is exposed in your app.

 While the @alias tag may sound similar to the @name tag, these tags behave very differently. The @name tag tells JSDoc to ignore any code associated with the comment. For example, when JSDoc processes the following code, it ignores the fact that the comment for `bar` is attached to a function:

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

```
 The @alias tag tells JSDoc to pretend that Member A is actually named Member B. For example, when JSDoc processes the following code, it recognizes that `foo` is a function, then renames `foo` to `bar` in the documentation:

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

```
 Examples
--------

 Suppose you are using a class framework that expects you to pass in a constructor function when you define a class. You can use the @alias tag to tell JSDoc how the class will be exposed in your app.

 In the following example, the @alias tag tells JSDoc to treat the anonymous function as if it were the constructor for the class "trackr.CookieManager". Within the function, JSDoc interprets the `this` keyword relative to trackr.CookieManager, so the "value" method has the namepath "trackr.CookieManager#value".

 Using @alias with an anonymous constructor function 
```
Klass('trackr.CookieManager',

    /**
     * @class
     * @alias trackr.CookieManager
     * @param {Object} kv
     */
    function(kv) {
        /** The value. */
        this.value = kv;
    }

);

```
 You can also use the @alias tag with members that are created within an immediately invoked function expression (IIFE). The @alias tag tells JSDoc that these members are exposed outside of the IIFE's scope.

 Using @alias for static members of a namespace 
```
/** @namespace */
var Apple = {};

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

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

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

```
 For members that are defined within an object literal, you can use the @alias tag as an alternative to the [@lends](tags-lends) tag.

 Using @alias for an object literal 
```
// 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;
})();

```
 Related Links
-------------

 * [@name](tags-name)
* [@lends](tags-lends)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-alias.html>

@async
======

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Example](#example)

 Syntax
------

 `@async`

 Overview
--------

 The `@async` tag indicates that a function is [asynchronous](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function), meaning that it was declared using the syntax `async function foo() {}`. Do not use this tag for other types of asynchronous functions, such as functions that provide a callback. This tag is available in JSDoc 3.5.0 and later.

 In general, you do not need to use this tag, because JSDoc automatically detects asynchronous functions and identifies them in the generated documentation. However, if you are writing a virtual comment for an asynchronous function that does not appear in your code, you can use this tag to tell JSDoc that the function is asynchronous.

 Example
-------

 The following example shows a virtual comment that uses the `@async` tag:

 Virtual comment with @async tag 
```
/**
 * Download data from the specified URL.
 *
 * @async
 * @function downloadData
 * @param {string} url - The URL to download from.
 * @return {Promise<string>} The data from the URL.
 */

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-async.html>

@augments
=========

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Synonyms
--------

  `@extends` 

 Syntax
------

 `@augments <namepath>`

 Overview
--------

 The `@augments` or`@extends` tag indicates that a symbol inherits from, and potentially adds to, a parent symbol. You can use this tag to document both class-based and prototype-based inheritance.

 In JSDoc 3.3.0 and later, if a symbol inherits from multiple parents, and both parents have identically named members, JSDoc uses the documentation from the last parent that is listed in the JSDoc comment.

 Examples
--------

 In the following example, the `Duck` class is defined as a subclass of `Animal`. `Duck` instances have the same properties as `Animal` instances, as well as a `speak` method that is unique to `Duck` instances.

 Documenting a class/subclass relationship 
```
/**
 * @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)

```
 In the following example, the `Duck` class inherits from both the `Flyable` and `Bird` classes, both of which define a `takeOff` method. Because the documentation for `Duck` lists `@augments Bird` last, JSDoc automatically documents `Duck#takeOff` using the comment from `Bird#takeOff`.

 Multiple inheritance with duplicated method names 
```
/**
 * Abstract class for things that can fly.
 * @class
 */
function Flyable() {
    this.canFly = true;
}

/** Take off. */
Flyable.prototype.takeOff = function() {
    // ...
};

/**
 * Abstract class representing a bird.
 * @class
 */
function Bird(canFly) {
    this.canFly = canFly;
}

/** Spread your wings and fly, if possible. */
Bird.prototype.takeOff = function() {
    if (this.canFly) {
        this._spreadWings()
            ._run()
            ._flapWings();
    }
};

/**
 * Class representing a duck.
 * @class
 * @augments Flyable
 * @augments Bird
 */
function Duck() {}

// Described in the docs as "Spread your wings and fly, if possible."
Duck.prototype.takeOff = function() {
    // ...
};

```
 Related Links
-------------

 * [@borrows](tags-borrows)
* [@class](tags-class)
* [@mixes](tags-mixes)
* [@mixin](tags-mixin)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-augments.html>

@borrows
========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)

 Syntax
------

 `@borrows <that namepath> as <this namepath>`

 Overview
--------

 The @borrows tag allows you to add documentation for another symbol to your documentation.

 This tag would be useful if you had more than one way to reference a function, but you didn't want to duplicate the same documentation in two places.

 Examples
--------

 In this example there exists documentation for the "trstr" function, but "util.trim" is just a reference to that same function by a different name.

 Duplicate the documentation for trstr as util.trim 
```
/**
 * @namespace
 * @borrows trstr as trim
 */
var util = {
    trim: trstr
};

/**
 * Remove whitespace from around a string.
 * @param {string} str
 */
function trstr(str) {
}

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-borrows.html>

@classdesc
==========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@classdesc <some description>`

 Overview
--------

 The @classdesc tag is used to provide a description for a class, separate from the constructor function's description. Use the @classdesc tag in combination with the [@class (or @constructor) tag](tags-class).

 The functionality of the @classdesc tag in JSDoc 3 duplicates that of the @class in previous versions. As of version 3, the syntax and functionality of the @class tag now exactly matches the @constructor tag, and the @classdesc tag more explicitly communicates its purpose: to document a class's description.

 Examples
--------

 As shown below, a class has places for two descriptions, one applies to the function itself, while the other applies to the class in general.

 A doclet with both a constructor function description and a class description 
```
/**
 * This is a description of the MyClass constructor function.
 * @class
 * @classdesc This is a description of the MyClass class.
 */
function MyClass() {
}

```
 Related Links
-------------

 * [@class](tags-class)
* [@description](tags-description)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-classdesc.html>

@constant
=========

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Synonyms
--------

  `@const` 

 Syntax
------

 `@constant [<type> <name>]`

 Overview
--------

 The @constant tag is used to mark the documentation as belonging to a symbol that is a constant.

 Examples
--------

 In this example we are documenting a string constant. Note that although the code is using the `const` keyword, this is not required by JSDoc. If your JavaScript host environment doesn't yet support constant declarations, the @const documentation can just as effectively be used on `var` declarations.

 A string constant representing the color red 
```
/** @constant
    @type {string}
    @default
*/
const RED = 'FF0000';

/** @constant {number} */
var ONE = 1;

```
 Note that the example provides the type in a @type tag. This is optional. Also the optional @default tag is used here too, this will automatically add whatever the assigned value is (for example 'FF0000') to the documentation.

 Related Links
-------------

 * [@default](tags-default)
* [@type](tags-type)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-constant.html>

@copyright
==========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@copyright <some copyright text>`

 Overview
--------

 The @copyright tag is used to document copyright information in a file overview comment. Use this tag in combination with the [@file tag](tags-file).

 Examples
--------

 
```
/**
 * @file This is my cool script.
 * @copyright Michael Mathews 2011
 */

```
 Related Links
-------------

  [@file](tags-file) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-copyright.html>

@callback
=========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@callback <namepath>`

 Overview
--------

 The @callback tag provides information about a callback function that can be passed to other functions, including the callback's parameters and return value. You can include any of the tags that you can provide for a @method.

 Once you define a callback, you can use it in the same way as a custom type defined with the @typedef tag. In particular, you can use the callback's name as a type name. This allows you to indicate that a function parameter should contain a certain type of callback.

 If you want a callback to be displayed with the type definitions for a specific class, you can give the callback a namepath indicating that it is an inner function of that class. You can also define a global callback type that is referenced from multiple classes.

 Examples
--------

 Documenting a class-specific callback 
```
/**
 * @class
 */
function Requester() {}

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

/**
 * This callback is displayed as part of the Requester class.
 * @callback Requester~requestCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */

```
 Documenting a global callback 
```
/**
 * @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
 */

```
 Related Links
-------------

 * [@function](tags-function)
* [@typedef](tags-typedef)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-callback.html>

@class
======

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Synonyms
--------

  `@constructor` 

 Syntax
------

 `@class [<type> <name>]`

 Overview
--------

 The @class tag marks a function as being a constructor, meant to be called with the new keyword to return an instance.

 Examples
--------

 A function that constructs Person instances. 
```
/**
 * Creates a new Person.
 * @class
 */
function Person() {
}

var p = new Person();

```
 Related Links
-------------

  [@constructs](tags-constructs) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-class.html>

@constructs
===========

 Table of Contents
-----------------

 * [Overview](#overview)
* [Syntax](#syntax)
* [Examples](#examples)
* [Related Links](#related-links)

 Overview
--------

 When using an object literal to define a class (for example with the `@lends` tag) the `@constructs` tag allows you to document that a particular function will be used to construct instances of that class.

 Syntax
------

 `@constructs [<name>]`

 Examples
--------

 Using the @constructs tag with @lends 
```
var Person = makeClass(
    /** @lends Person.prototype */
    {
        /** @constructs */
        initialize: function(name) {
            this.name = name;
        },
        /** Describe me. */
        say: function(message) {
            return this.name + " says: " + message;
        }
    }
);

```
 Without @lends you must provide the name of the class 
```
makeClass('Menu',
    /**
     * @constructs Menu
     * @param items
     */
    function (items) { },
    {
        /** @memberof Menu# */
        show: function(){
        }
    }
);

```
 Related Links
-------------

  [@lends](tags-lends) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-constructs.html>

@default
========

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)

 Synonyms
--------

  `@defaultvalue` 

 Syntax
------

 `@default [<some value>]`

 Overview
--------

 The @default tag allows you to document the assigned value of a symbol. You can supply this tag with a value yourself or you can allow JSDoc to automatically document the value from the source code -- only possible when the documented symbol is being assigned a single, simple value that is either: a string, a number, a boolean or null.

 Examples
--------

 In this example a constant is documented. The value of the constant is `0xff0000`. By adding the @default tag this value is automatically added to the documentation.

 Document the number value of a constant 
```
/**
 *  @constant
 *  @default
 */
const RED = 0xff0000;

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-default.html>

@deprecated
===========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)

 Syntax
------

 `@deprecated [<some text>]`

 Overview
--------

 The @deprecated tag marks a symbol in your code as being deprecated.

 Examples
--------

 You can use the @deprecated tag by itself, or include some text that describes more about the deprecation.

 Document that the old function has been deprecated since version 2.0 
```
/**
 * @deprecated since version 2.0
 */
function old() {
}

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-deprecated.html>

@description
============

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Synonyms
--------

  `@desc` 

 Syntax
------

 `@description <some description>`

 Overview
--------

 The @description tag allows you to provide a general description of the symbol you are documenting. The description may include HTML markup. It may also include Markdown formatting if the [Markdown plugin](plugins-markdown) is enabled.

 Examples
--------

 If you describe a symbol at the very beginning of a JSDoc comment, before using any block tags, you may omit the @description tag.

 Describing a symbol without the @description tag 
```
/**
 * Add two numbers.
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function add(a, b) {
    return a + b;
}

```
 By using the @description tag, you can place the description anywhere in the JSDoc comment.

 Describing a symbol with the @description tag 
```
/**
 * @param {number} a
 * @param {number} b
 * @returns {number}
 * @description Add two numbers.
 */
function add(a, b) {
    return a + b;
}

```
 If there's both a description at the beginning of a JSDoc comment and a description provided with the @description tag, the description specified with the @description will override the description at the beginning of the comment.

 Related Links
-------------

 * [@classdesc](tags-classdesc)
* [@summary](tags-summary)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-description.html>

@enum
=====

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@enum [<type>]`

 Overview
--------

 The @enum tag documents a collection of static properties whose values are all of the same type.

 An enum is similar a collection of properties, except that an enum is documented in its own doc comment, whereas properties are documented within the doc comment of their container. Often this tag is used with @readonly, as an enum typically represents a collection of constants.

 Examples
--------

 This shows how to document an object that represents a value with three possible states. Note that the enum members can have optional descriptions added if you wish. Also you can override the type, as is shown with "MAYBE" -- by default enum members will be documented with the same type as the enum itself.

 A numeric enum, representing three states 
```
/**
 * Enum for tri-state values.
 * @readonly
 * @enum {number}
 */
var triState = {
    /** The true value */
    TRUE: 1,
    FALSE: -1,
    /** @type {boolean} */
    MAYBE: true
};

```
 Related Links
-------------

  [@property](tags-property) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-enum.html>

@event
======

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@event <className>#[event:]<eventName>`

 Overview
--------

 The @event tag allows you to document an event that can be fired. A typical event is represented by an object with a defined set of properties.

 Once you have used the @event tag to define a specific type of event, you can use the @fires tag to indicate that a method can fire that event. You can also use the @listens tag to indicate that a symbol listens for the event.

 JSDoc automatically prepends the namespace `event:` to each event's name. In general, you must include this namespace when you link to the event in another doclet. (The @fires tag is a notable exception; it allows you to omit the namespace.)

 **Note**: JSDoc 3 uses @event doclets to document the content of an event. In contrast, JSDoc Toolkit 2 used @event doclets to identify a function that can be fired when an event of the same name occurs.

 Examples
--------

 The following examples show how to document an event in the `Hurl` class called `snowball`. The event contains an object with a single property.

 Documenting a function call as an event 
```
/**
 * 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.
     */
    this.emit('snowball', {
        isPacked: this._snowball.isPacked
    });
};

```
 Using a named doclet to document an event 
```
/**
 * 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.
 */

```
 Related Links
-------------

 * [@fires](tags-fires)
* [@listens](tags-listens)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-event.html>

@example
========

 Table of Contents
-----------------

 * [Overview](#overview)
* [Examples](#examples)

 Overview
--------

 Provide an example of how to use a documented item. The text that follows this tag will be displayed as highlighted code.

 Examples
--------

 Note that a doclet may have multiple examples.

 Documenting examples 
```
/**
 * 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;
};

```
 Examples can also be captioned using `<caption></caption>` after the @example tag.

 Documenting examples with a caption 
```
/**
 * Solves equations of the form a * x = b
 * @example <caption>Example usage of method1.</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;
};

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-example.html>

@exports
========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@exports <moduleName>`

 In JSDoc 3.3.0 and later, `<moduleName>` may include the `module:` prefix. In previous versions, you must omit this prefix.

 Overview
--------

 Use the @exports tag when documenting JavaScript modules that export anything other than the "exports" object or the "module.exports" property.

 Examples
--------

 In modules where you are using the special "exports" object, the @exports tag is never needed. JSDoc automatically recognizes that this object's members are being exported. Similarly, JSDoc automatically recognizes the special "module.exports" property in Node.js modules.

 CommonJS module 
```
/**
 * A module that says hello!
 * @module hello/world
 */

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

```
 Node.js module 
```
/**
 * A module that shouts hello!
 * @module hello/world
 */

/** SAY HELLO. */
module.exports = function() {
    return "HELLO WORLD";
};

```
 AMD module that exports an object literal 
```
define(function() {

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

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

    return exports;
});

```
 AMD module that exports a constructor 
```
define(function() {
    /**
     * A module that creates greeters.
     * @module greeter
     */

    /**
     * @constructor
     * @param {string} subject - The subject to greet.
     */
    var exports = function(subject) {
        this.subject = subject || 'world';
    };

    /** Say hello to the subject. */
    exports.prototype.sayHello = function() {
        return 'Hello ' + this.subject;
    };

    return exports;
});

```
 If your module exports an object named anything other than "exports" or "module.exports", use the @exports tag to indicate what is being exported.

 AMD module that exports an object 
```
define(function () {

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

    /** Say hello. */
    ns.sayHello = function() {
        return 'Hello world';
    };

    return ns;
});

```
 Related Links
-------------

 * [@module](tags-module)
* [CommonJS Modules](howto-commonjs-modules)
* [AMD Modules](howto-amd-modules)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-exports.html>

@external
=========

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)

 Synonyms
--------

  `@host` 

 Syntax
------

 `@external <NameOfExternal>`

 Overview
--------

 The `@external` tag identifies a class, namespace, or module that is defined outside of the current package. By using this tag, you can document your package's extensions to the external symbol, or you can provide information about the external symbol to your package's users. You can also refer to the external symbol's namepath in any other JSDoc tag.

 The namepath for an external symbol always uses the prefix `external:` (for example, `{@link external:Foo}` or `@augments external:Foo`). However, you can omit this prefix from the `@external` tag.

 **Note**: You should only add the `@external` tag to the highest-level symbol that is defined outside of your project. See "[Documenting a nested external symbol](#nested-external-symbol)" for an example.

 Examples
--------

 The following example shows how to document the built-in `String` object as an external, along with the new instance method `external:String#rot13`:

 Documenting methods added to built-in classes 
```
/**
 * 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
 */

```
 The following example documents a new `starfairy` function added to the external namespace `"jQuery.fn"`:

 Documenting external namespaces 
```
/**
 * 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
 */

```
 In the following example, the class `EncryptedRequest` is documented as a subclass of the built-in class `XMLHttpRequest`:

 Extending an external. 
```
/**
 * The built-in class for sending HTTP requests.
 * @external XMLHttpRequest
 * @see https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
 */

/**
 * Extends the built-in `XMLHttpRequest` class to send data encoded with a secret key.
 * @class EncodedRequest
 * @extends external:XMLHttpRequest
 */

```
  You should only add the `@external` tag to the highest-level symbol that is defined outside of your project. In the following example, the documentation refers to the external class `security.TLS`. As a result, the `@external` tag is used to document the external namespace `external:security`, but *not* the external class `external:security.TLS`.

 Documenting a nested external symbol 
```
/**
 * External namespace for security-related classes.
 * @external security
 * @see http://example.org/docs/security
 */

/**
 * External class that provides Transport Layer Security (TLS) encryption.
 * @class TLS
 * @memberof external:security
 */

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-external.html>

@file
=====

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Overview](#overview)
* [Example](#example)
* [Related Links](#related-links)

 Synonyms
--------

 * `@fileoverview`
* `@overview`

 Overview
--------

 The @file tag provides a description for a file. Use the tag in a JSDoc comment at the beginning of the file.

 Example
-------

 File description 
```
/**
 * @file Manages the configuration settings for the widget.
 * @author Rowina Sanela 
 */

```
 Related Links
-------------

 * [@author](tags-author)
* [@version](tags-version)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-file.html>

@fires
======

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Synonyms
--------

  `@emits` 

 Syntax
------

 `@fires <className>#[event:]<eventName>`

 Overview
--------

 The @fires tag indicates that a method can fire a specified type of event when it is called. Use the [@event tag](tags-event) to document the event's content.

 Examples
--------

 Method that fires a 'drain' event 
```
/**
 * Drink the milkshake.
 *
 * @fires Milkshake#drain
 */
Milkshake.prototype.drink = function() {
    // ...
};

```
 Related Links
-------------

 * [@event](tags-event)
* [@listens](tags-listens)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-fires.html>

@function
=========

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)

 Synonyms
--------

 * `@func`
* `@method`

 Syntax
------

 `@function [<FunctionName>]`

 Overview
--------

 This marks an object as being a function, even though it may not appear to be one to the parser. It sets the doclet's [@kind](tags-kind) to 'function'.

 Examples
--------

 Using @function to mark a function. 
```
/** @function */
var paginate = paginateFactory(pages);

```
 Without the @function tag, the `paginate` object would be documented as a generic object (a [@member](tags-member)), because it isn't possible to tell from examining the line of code what type of value `paginate` will hold when it is run.

 Using @function with a name. 
```
/** @function myFunction */

// the above is the same as:
/** @function
 * @name myFunction */

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-function.html>

@global
=======

 Table of Contents
-----------------

 * [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Overview
--------

 The @global tag specifies that a symbol should appear in the documentation as a *global* symbol. JSDoc ignores the symbol's actual scope within the source file. This tag is especially useful for symbols that are defined locally, then assigned to a global symbol.

 Examples
--------

 Use the @global tag to specify that a symbol should be documented as global.

 Document an inner variable as a global 
```
(function() {
    /** @global */
    var foo = 'hello foo';

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

```
 Related Links
-------------

 * [@inner](tags-inner)
* [@instance](tags-instance)
* [@memberof](tags-memberof)
* [@static](tags-static)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-global.html>

@generator
==========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Example](#example)

 Syntax
------

 `@generator`

 Overview
--------

 The `@generator` tag indicates that a function is a [generator function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*), meaning that it was declared using the syntax `function* foo() {}`. This tag is available in JSDoc 3.5.0 and later.

 In general, you do not need to use this tag, because JSDoc automatically detects generator functions and identifies them in the generated documentation. However, if you are writing a virtual comment for a generator function that does not appear in your code, you can use this tag to tell JSDoc that the function is a generator function.

 Example
-------

 The following example shows a virtual comment that uses the `@generator` tag:

 Virtual comment with @generator tag 
```
/**
 * Generate numbers in the Fibonacci sequence.
 *
 * @generator
 * @function fibonacci
 * @yields {number} The next number in the Fibonacci sequence.
 */

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-generator.html>

@hideconstructor
================

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@hideconstructor`

 Overview
--------

 The `@hideconstructor` tag tells JSDoc that the generated documentation should not display the constructor for a class. This tag is available in JSDoc 3.5.0 and later.

 For pre-ES2015 classes, use this tag in combination with the [`@class` or `@constructor` tag](tags-class).

 For ES2015 classes, use this tag in the JSDoc comment for your constructor. If your class does not have an explicit constructor, use this tag in the JSDoc comment for the class.

 Examples
--------

 @hideconstructor tag with pre-ES2015 class 
```
/**
 * @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;
        }
    };
})();

```
 @hideconstructor tag with ES2015 class 
```
/**
 * Waffle iron singleton.
 */
class WaffleIron {
    #instance = null;

    /**
     * Create the waffle iron.
     *
     * @hideconstructor
     */
    constructor() {
        if (#instance) {
            return #instance;
        }

        /**
         * Cook a waffle.
         *
         * @param {Batter} batter - The waffle batter.
         * @return {Waffle} The cooked waffle.
         */
        this.cook = function(batter) {};

        this.#instance = this;
    }

    /**
     * Get the WaffleIron instance.
     *
     * @return {WaffleIron} The WaffleIron instance.
     */
    getInstance() {
        return new WaffleIron();
    }
}

```
 Related Links
-------------

  [@class](tags-class) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-hideconstructor.html>

@ignore
=======

 Table of Contents
-----------------

 * [Overview](#overview)
* [Examples](#examples)

 Overview
--------

 The `@ignore` tag indicates that a symbol in your code should never appear in the documentation. This tag takes precedence over all others.

 For most JSDoc templates, including the default template, the `@ignore` tag has the following effects:

 * If you use the `@ignore` tag with the `@class` or `@module` tag, the entire class or module will be omitted from the documentation.
* If you use the `@ignore` tag with the `@namespace` tag, you must also add the `@ignore` tag to any child classes and namespaces. Otherwise, your documentation will show the child classes and namespaces, but with incomplete names.

 Examples
--------

 In the following example, `Jacket` and `Jacket#color` will not appear in the documentation.

 Class with `@ignore` tag 
```
/**
 * @class
 * @ignore
 */
function Jacket() {
    /** The jacket's color. */
    this.color = null;
}

```
 In the following example, the `Clothes` namespace contains a `Jacket` class. The `@ignore` tag must be added to both `Clothes` and `Clothes.Jacket`. `Clothes`, `Clothes.Jacket`, and `Clothes.Jacket#color` will not appear in the documentation.

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

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-ignore.html>

@inheritdoc
===========

 Table of Contents
-----------------

 * [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Overview
--------

 The `@inheritdoc` tag indicates that a symbol should inherit its documentation from its parent class. Any other tags that you include in the JSDoc comment will be ignored.

 This tag is provided for compatibility with [Closure Compiler](https://developers.google.com/closure/compiler/). By default, if you do not add a JSDoc comment to a symbol, the symbol will inherit documentation from its parent.

 The presence of the `@inheritdoc` tag implies the presence of the [`@override` tag](tags-override).

 Examples
--------

 The following example shows how a class can indicate that it inherits documentation from its parent class:

 Class that inherits from a parent class 
```
/**
 * @classdesc Abstract class representing a network connection.
 * @class
 */
function Connection() {}

/**
 * Open the connection.
 */
Connection.prototype.open = function() {
    // ...
};


/**
 * @classdesc Class representing a socket connection.
 * @class
 * @augments Connection
 */
function Socket() {}

/** @inheritdoc */
Socket.prototype.open = function() {
    // ...
};

```
 You can get the same result by omitting the JSDoc comment from `Socket#open`:

 Inheriting documentation without the `@inheritdoc` tag 
```
/**
 * @classdesc Abstract class representing a network connection.
 * @class
 */
function Connection() {}

/**
 * Open the connection.
 */
Connection.prototype.open = function() {
    // ...
};


/**
 * @classdesc Class representing a socket connection.
 * @class
 * @augments Connection
 */
function Socket() {}

Socket.prototype.open = function() {
    // ...
};

```
 Related Links
-------------

  [@override](tags-override) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-inheritdoc.html>

@implements
===========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@implements {typeExpression}`

 Overview
--------

 The `@implements` tag indicates that a symbol implements an interface.

 Add the `@implements` tag to the top-level symbol that implements the interface (for example, a constructor function). You do not need to add the `@implements` tag to each member of the implementation (for example, the implementation's instance methods).

 If you do not document one of the symbols in the implementation, JSDoc will automatically use the interface's documentation for that symbol.

 Examples
--------

 In the following example, the `TransparentColor` class implements the `Color` interface and adds a `TransparentColor#rgba` method.

 Using the @implements tag 
```
/**
 * 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() {
    // ...
};

```
 Related Links
-------------

  [@interface](tags-interface) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-implements.html>

@inner
======

 Table of Contents
-----------------

 * [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Overview
--------

 Using the @inner tag will mark a symbol as an inner member of its parent symbol. This means it can be referred to by "Parent~Child".

 Using @inner will override a doclet's default scope (unless it is in the global scope, in which case it will remain global).

 Examples
--------

 Using @inner to make a virtual doclet an inner member 
```
/** @namespace MyNamespace */
/**
 * myFunction is now MyNamespace~myFunction.
 * @function myFunction
 * @memberof MyNamespace
 * @inner
 */

```
 Note that in the above we could have used "@function MyNamespace~myFunction" instead of the @memberof and @inner tags.

 Using @inner 
```
/** @namespace */
var MyNamespace = {
    /**
     * foo is now MyNamespace~foo rather than MyNamespace.foo.
     * @inner
     */
    foo: 1
};

```
 In the above example, we use @inner to force a member of a namespace to be documented as an inner member (by default, it would be a static member). This means that `foo` now has the longname `MyNamespace~foo` instead of `MyNamespace.foo`.

 Related Links
-------------

 * [@global](tags-global)
* [@instance](tags-instance)
* [@static](tags-static)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-inner.html>

@interface
==========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 With the JSDoc tag dictionary (enabled by default):

 `@interface [<name>]`

 With the [Closure Compiler](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#jsdoc-tags) tag dictionary:

 `@interface`

 Overview
--------

 The `@interface` tag marks a symbol as an interface that other symbols can implement. For example, your code might define a parent class whose methods and properties are stubbed out. You can add the `@interface` tag to the parent class to indicate that child classes must implement the parent class' methods and properties.

 Add the `@interface` tag to the top-level symbol for the interface (for example, a constructor function). You do not need to add the `@interface` tag to each member of the interface (for example, the interface's instance methods).

 If you are using the JSDoc tag dictionary (enabled by default), you can also define an interface with virtual comments, rather than by writing code for the interface. See "[Virtual comments that define an interface](#virtual-comments)" for an example.

 Examples
--------

 In the following example, the `Color` function represents an interface that other classes can implement:

 Using the @interface tag 
```
/**
 * 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');
};

```
  The following example uses virtual comments, rather than code, to define the `Color` interface:

 Virtual comments that define an interface 
```
/**
 * Interface for classes that represent a color.
 *
 * @interface Color
 */

/**
 * Get the color as an array of red, green, and blue values, represented as
 * decimal numbers between 0 and 1.
 *
 * @function
 * @name Color#rgb
 * @returns {Array<number>} An array containing the red, green, and blue values,
 * in that order.
 */

```
 Related Links
-------------

  [@implements](tags-implements) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-interface.html>

@instance
=========

 Table of Contents
-----------------

 * [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Overview
--------

 Using the @instance tag will mark a symbol as an instance member of its parent symbol. This means it can be referred to by "Parent#Child".

 Using @instance will override a doclet's default scope (unless it is in the global scope, in which case it will remain global).

 Examples
--------

 The following example is a longhand way of writing "@function MyNamespace#myFunction":

 Using @instance to make a virtual doclet an instance member 
```
/** @namespace MyNamespace */
/**
 * myFunction is now MyNamespace#myFunction.
 * @function myFunction
 * @memberof MyNamespace
 * @instance
 */

```
 More usefully, you can use the @instance tag to override the scope that JSDoc infers. For example, you can indicate that a static member is used as an instance member:

 Using @instance to identify an instance member 
```
/** @namespace */
var BaseObject = {
    /**
     * foo is now BaseObject#foo rather than BaseObject.foo.
     * @instance
     */
    foo: null
};

/** Generates BaseObject instances. */
function fooFactory(fooValue) {
    var props = { foo: fooValue };
    return Object.create(BaseObject, props);
}

```
 Related Links
-------------

 * [@global](tags-global)
* [@inner](tags-inner)
* [@static](tags-static)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-instance.html>

@kind
=====

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@kind <kindName>`

 where `<kindName>` is one of:

 * class
* constant
* event
* external
* file
* function
* member
* mixin
* module
* namespace
* typedef

 Overview
--------

 The @kind tag is used to document what *kind* of symbol is being documented (for example, a class or a module). The *kind* of symbol differs from a symbol's *type* (for example, string or boolean).

 Usually you do not need the @kind tag, because the symbol's kind is determined by other tags in the doclet. For example, using the @class tag automatically implies "@kind class", and using the @namespace tag implies "@kind namespace".

 Examples
--------

 Using @kind 
```
// The following examples produce the same result:

/**
 * A constant.
 * @kind constant
 */
const asdf = 1;

/**
 * A constant.
 * @constant
 */
const asdf = 1;

```
 In the case of tags with conflicting kinds (for example, using both @module, which sets the kind to "module", and "@kind constant" which sets the kind to "constant"), the last tag determines the kind.

 Conflicting @kind statements 
```
/**
 * This will show up as a constant
 * @module myModule
 * @kind constant
 */

/**
 * This will show up as a module.
 * @kind constant
 * @module myModule
 */

```
 Related Links
-------------

  [@type](tags-type) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-kind.html>

@license
========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)

 Syntax
------

 `@license <identifier>`

 Overview
--------

 The `@license` tag identifies the software license that applies to any portion of your code.

 You can use any text to identify the license you are using. If your code uses a standard open-source license, consider using the appropriate identifier from the [Software Package Data Exchange (SPDX) License List](https://spdx.org/licenses/).

 Some JavaScript processing tools, such as Google's Closure Compiler, will automatically preserve any JSDoc comment that includes a `@license` tag. If you are using one of these tools, you may wish to add a standalone JSDoc comment that includes the `@license` tag, along with the entire text of the license, so that the license text will be included in generated JavaScript files.

 Examples
--------

 A module that is distributed under the Apache License 2.0 
```
/**
 * Utility functions for the foo package.
 * @module foo/util
 * @license Apache-2.0
 */

```
 A standalone JSDoc comment with the complete MIT license 
```
/**
 * @license
 * Copyright (c) 2015 Example Corporation Inc.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-license.html>

@listens
========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Example](#example)
* [Related Links](#related-links)

 Syntax
------

 `@listens <eventName>`

 Overview
--------

 The `@listens` tag indicates that a symbol listens for the specified event. Use the [`@event tag`](tags-event) to document the event's content.

 Example
-------

 The following example shows how to document an event named `module:hurler~event:snowball`, as well as a method named `module:playground/monitor.reportThrowage` that listens for the event.

 Documenting an event and its listener 
```
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;
});

```
 Related Links
-------------

 * [@event](tags-event)
* [@fires](tags-fires)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-listens.html>

@member
=======

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)

 Synonyms
--------

  `@var` 

 Syntax
------

 `@member [<type>] [<name>]`

 Overview
--------

 The @member tag identifies any member that does not have a more specialized kind, such as "class", "function", or "constant". A member can optionally have a type as well as a name.

 Examples
--------

 Using @member with Data#point 
```
/** @class */
function Data() {
    /** @member {Object} */
    this.point = {};
}

```
 Here is an example of using @var, a synonym of @member, to document a (virtual) variable 'foo'.

 Using @var to document a virtual member 
```
/**
 * A variable in the global namespace called 'foo'.
 * @var {number} foo
 */

```
 The above example is equivalent to the following:

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

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-member.html>

@mixes
======

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@mixes <OtherObjectPath>`

 Overview
--------

 The @mixes tag indicates that the current object mixes in all the members from `OtherObjectPath`, which is a [@mixin](tags-mixin).

 Examples
--------

 To start, we document a mixin with the [@mixin](tags-mixin) tag:

 Example of a @mixin 
```
/**
 * 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...
    }
};

```
 Now we add a FormButton class and call a "mix" function that mixes all of the Eventful functions into FormButton, so that FormButton can also fire events and have listeners. We use the @mixes tag to indicate that FormButton mixes the Eventful functions.

 Using the @mixes tag 
```
/**
 * @constructor FormButton
 * @mixes Eventful
 */
var FormButton = function() {
    // code...
};
FormButton.prototype.press = function() {
  this.fire('press', {});
}
mix(Eventful).into(FormButton.prototype);

```
 Related Links
-------------

 * [@borrows](tags-borrows)
* [@class](tags-class)
* [@mixin](tags-mixin)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-mixes.html>

@mixin
======

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@mixin [<MixinName>]`

 Overview
--------

 A mixin provides functionality that is intended to be added to other objects. If desired, you can use the @mixin tag to indicate that an object is a mixin. You can then add the @mixes tag to objects that use the mixin.

 Examples
--------

 Using @mixin 
```
/**
 * 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...
    }
};

```
 Related Links
-------------

 * [@borrows](tags-borrows)
* [@class](tags-class)
* [@mixes](tags-mixes)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-mixin.html>

@module
=======

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@module [[{<type>}] <moduleName>]`

 In JSDoc 3.3.0 and later, `<moduleName>` may include the `module:` prefix. In previous versions, you must omit this prefix.

 Note: If you provide a type, you *must* also provide a name.

 Overview
--------

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

 Link to a module (e.g. within a [@link](tags-inline-link) or [@see](tags-see) tag) using "module:moduleName". For example, "@module foo/bar" can be linked to using "{@link module:foo/bar}".

 If the module name is not provided, it is derived from the module's path and filename. For example, suppose I have a file `test.js`, located in the `src` directory, that contains the block comment `/** @module */`. Here are some scenarios for running JSDoc and the resulting module names for test.js:

 Derived module names if none is provided. 
```
# from src/
jsdoc ./test.js   # module name 'test'

# from src's parent directory:
jsdoc src/test.js # module name 'src/test'
jsdoc -r src/     # module name 'test'

```
 Examples
--------

 The following example shows the namepaths that are used for symbols in a module. The first symbol is a module-private, or "inner," variable--it can be only accessed within the module. The second symbol is a static function that is exported by the module.

 Basic @module use 
```
/** @module myModule */

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

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

```
 When an exported symbol is defined as a member of `module.exports`, `exports`, or `this`, JSDoc infers that the symbol is a static member of the module.

 In the following example, the Book class is documented as a static member, "module:bookshelf.Book", with one instance member, "module:bookshelf.Book#title".

 Defining exported symbols as a member of 'this' 
```
/** @module bookshelf */
/** @class */
this.Book = function (title) {
    /** The title. */
    this.title = title;
};

```
 In the following example, the two functions have the namepaths "module:color/mixer.blend" and "module:color/mixer.darken".

 Defining exported symbols as a member of 'module.exports' or 'exports' 
```
/** @module color/mixer */
module.exports = {
    /** Blend two colours together. */
    blend: function (color1, color2) {}
};
/** Darkens a color. */
exports.darken = function (color, shade) {};

```
 See [Documenting JavaScript Modules](howto-commonjs-modules) for further examples.

 Related Links
-------------

 * [@exports](tags-exports)
* [CommonJS Modules](howto-commonjs-modules)
* [AMD Modules](howto-amd-modules)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-module.html>

@package
========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 With the JSDoc tag dictionary (enabled by default):

 `@package`

 With the [Closure Compiler](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#jsdoc-tags) tag dictionary:

 `@package [{typeExpression}]`

 Overview
--------

 The `@package` tag marks a symbol as package-private. Typically, this tag indicates that a symbol is available only to code in the same directory as the source file for this symbol. This tag is available in JSDoc 3.5.0 and later.

 By default, symbols marked with the `@package` tag will appear in your documentation. In JSDoc 3.3.0 and later, you can use the [`-a/--access` command-line option](about-commandline) to change this behavior.

 The `@package` tag is equivalent to `@access package`.

 Examples
--------

 In the following example, the instance member `Thingy#_bar` appears in the generated documentation, but with an annotation indicating that it is package-private:

 Using the @package tag 
```
/** @constructor */
function Thingy() {
    /** @package */
    this._bar = 1;
}

```
 Related Links
-------------

 * [@access](tags-access)
* [@global](tags-global)
* [@instance](tags-instance)
* [@private](tags-private)
* [@protected](tags-protected)
* [@public](tags-public)
* [@static](tags-static)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-package.html>

@lends
======

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@lends <namepath>`

 Overview
--------

 The `@lends` tag allows you to document all the members of an object literal as if they were members of a symbol with the given name. You might want to do this if you are passing an object literal into a function that creates a named class from its members.

 Examples
--------

 In this example, we want to use a helper function to make a class named `Person`, along with instance methods named `initialize` and `say`. This is similar to how some popular frameworks handle class creation.

 Example class 
```
// We want to document this as being a class
var Person = makeClass(
    // We want to document these as being methods
    {
        initialize: function(name) {
            this.name = name;
        },
        say: function(message) {
            return this.name + " says: " + message;
        }
    }
);

```
 Without any comments, JSDoc won't recognize that this code creates a `Person` class with two methods. To document the methods, we must use a `@lends` tag in a doc comment immediately before the object literal. The `@lends` tag tells JSDoc that all the member names of that object literal are being "loaned" to a variable named `Person`. We must also add comments to each of the methods.

 The following example gets us closer to what we want:

 Documented as static methods 
```
/** @class */
var Person = makeClass(
    /** @lends Person */
    {
        /**
         * Create a `Person` instance.
         * @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;
        }
    }
);

```
 Now the functions named `initialize` and `say` will be documented, but they appear as static methods of the `Person` class. That is possibly what you meant, but in this case we want `initialize` and `say` to belong to the instances of the `Person` class. So we change things slightly by lending the methods to the class's prototype:

 Documented as instance methods 
```
/** @class */
var Person = makeClass(
    /** @lends Person.prototype */
    {
        /**
         * Create a `Person` instance.
         * @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;
        }
    }
);

```
 One final step: Our class framework uses the loaned `initialize` function to construct `Person` instances, but a `Person` instance does not have its own `initialize` method. The solution is to add the `@constructs` tag to the loaned function. Remember to remove the `@class` tag as well, or else two classes will be documented.

 Documented with a constructor 
```
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;
        }
    }
);

```
 Related Links
-------------

 * [@borrows](tags-borrows)
* [@constructs](tags-constructs)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-lends.html>

@memberof
=========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 * `@memberof <parentNamepath>`
* `@memberof! <parentNamepath>`

 Overview
--------

 The @memberof tag identifies a member symbol that belongs to a parent symbol.

 By default, the @memberof tag documents member symbols as static members. For inner and instance members, you can use scoping punctuation after the namepath, or you can add the [@inner](tags-inner) or [@instance](tags-instance) tag.

 The "forced" @memberof tag, @memberof!, forces the object to be documented as belonging to a specific parent even if it appears to have a different parent.

 Examples
--------

 In the following example, the `hammer` function would normally be documented as a global function. That's because, in fact, it is a global function, but it is also a member of the `Tools` namespace, and that's how you wish to document it. The solution is to add a @memberof tag:

 Using @memberof 
```
/** @namespace */
var Tools = {};

/** @memberof Tools */
var hammer = function() {
};

Tools.hammer = hammer;

```
 For instance members of a class, use the syntax "@memberof ClassName.prototype" or "@memberof ClassName#". Alternatively, you can combine "@memberof ClassName" with the "@instance" tag.

 Using @memberof with a class prototype 
```
/** @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() {}
    }
);

```
 The following example uses the forced @memberof tag, "@memberof!", to document a property of an object (Data#point) that is an instance member of a class (Data).

 When you use the @property tag to document a property, you cannot link to the property using its longname. We can force the property to be linkable by using "@alias" and "@memberof!" to tell JSDoc that Data#point.y should be documented as a member "point.y" of "Data#", rather than a member "y" of "point" of "Data#".

 Using @memberof! for object properties 
```
/** @class */
function Data() {
    /**
     * @type {object}
     * @property {number} y This will show up as a property of `Data#point`,
     * but you cannot link to the property as {@link Data#point.y}.
     */
    this.point = {
        /**
         * The @alias and @memberof! tags force JSDoc to document the
         * property as `point.x` (rather than `x`) and to be a member of
         * `Data#`. You can link to the property as {@link Data#point.x}.
         * @alias point.x
         * @memberof! Data#
         */
        x: 0,
        y: 1
    };
}

```
 Related Links
-------------

  [@name](tags-name) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-memberof.html>

@name
=====

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@name <namePath>`

 Overview
--------

 The @name tag forces JSDoc to associate the remainder of the JSDoc comment with the given name, ignoring all surrounding code. This tag is best used in "virtual comments" for symbols that are not readily visible in the code, such as methods that are generated at runtime.

 When you use the @name tag, you must provide additional tags that tell JSDoc what kind of symbol you are documenting; whether the symbol is a member of another symbol; and so on. If you do not provide this information, the symbol will not be documented correctly.

 **Warning**: By using the @name tag, you are telling JSDoc to *ignore the surrounding code* and treat your documentation comment in isolation. In many cases, it is best to use the [@alias tag](tags-alias) instead, which changes a symbol's name in the documentation but preserves other information about the symbol.

 Examples
--------

 The following example shows how to use the @name tag to document a function that JSDoc would not normally recognize.

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

```
 Related Links
-------------

 * [Using namepaths with JSDoc 3](about-namepaths)
* [@alias](tags-alias)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-name.html>

@namespace
==========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@namespace [[{<type>}] <SomeName>]`

 Overview
--------

 The @namespace tag indicates that an object creates a namespace for its members. You can also write a virtual JSDoc comment that defines a namespace used by your code.

 If a namespace is defined by a symbol other than an object literal, you can include a type expression along with the @namespace tag. If the @namespace tag includes a type, it must also include a name.

 You may need to document a namespace whose name includes unusual characters, such as "#" or "!". In these cases, when you document or link to the namespace, you must add quotation marks around the portion of the namespace that includes unusual characters. See the examples below for details.

 Examples
--------

 Using the @namespace tag with an object 
```
/**
 * My namespace.
 * @namespace
 */
var MyNamespace = {
    /** documented as MyNamespace.foo */
    foo: function() {},
    /** documented as MyNamespace.bar */
    bar: 1
};

```
 Using the @namespace tag for virtual comments 
```
/**
 * A namespace.
 * @namespace MyNamespace
 */

/**
 * A function in MyNamespace (MyNamespace.myFunction).
 * @function myFunction
 * @memberof MyNamespace
 */

```
 If a @namespace includes a symbol whose name has unusual characters, you must enclose the symbol's name in double quotes. If the symbol's name already contains one or more double quotes, escape the double quotes with a leading backslash (\).

 Using the @namespace tag with unusual member names 
```
/** @namespace window */

/**
 * Shorthand for the alert function.
 * Refer to it as {@link window."!"} (note the double quotes).
 */
window["!"] = function(msg) { alert(msg); };

```
 Related Links
-------------

  [@module](tags-module) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-namespace.html>

@override
=========

 Table of Contents
-----------------

 * [Overview](#overview)
* [Example](#example)
* [Related Links](#related-links)

 Overview
--------

 The `@override` tag indicates that a symbol overrides a symbol with the same name in a parent class.

 This tag is provided for compatibility with [Closure Compiler](https://developers.google.com/closure/compiler/). By default, JSDoc automatically identifies symbols that override a parent.

 If your JSDoc comment includes the [`@inheritdoc` tag](tags-inheritdoc), you do not need to include the `@override` tag. The presence of the `@inheritdoc` tag implies the presence of the `@override` tag.

 Example
-------

 The following example shows how to indicate that a method overrides a method in its parent class:

 Method that overrides a parent 
```
/**
 * @classdesc Abstract class representing a network connection.
 * @class
 */
function Connection() {}

/**
 * Open the connection.
 */
Connection.prototype.open = function() {
    // ...
};


/**
 * @classdesc Class representing a socket connection.
 * @class
 * @augments Connection
 */
function Socket() {}

/**
 * Open the socket.
 * @override
 */
Socket.prototype.open = function() {
    // ...
};

```
 Related Links
-------------

  [@inheritdoc](tags-inheritdoc) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-override.html>

@param
======

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Overview](#overview)
* [Examples](#examples)
	+ [Names, types, and descriptions](#names-types-and-descriptions)
	+ [Parameters with properties](#parameters-with-properties)
	+ [Optional parameters and default values](#optional-parameters-and-default-values)
	+ [Multiple types and repeatable parameters](#multiple-types-and-repeatable-parameters)
	+ [Callback functions](#callback-functions)
* [Related Links](#related-links)

 Synonyms
--------

 * `@arg`
* `@argument`

 Overview
--------

 The `@param` tag provides the name, type, and description of a function parameter.

 The `@param` tag requires you to specify the name of the parameter you are documenting. You can also include the parameter's type, enclosed in curly brackets, and a description of the parameter.

 The parameter type can be a built-in JavaScript type, such as `string` or `Object`, or a [JSDoc namepath](about-namepaths) to another symbol in your code. If you have written documentation for the symbol at that namepath, JSDoc will automatically link to the documentation for that symbol. You can also use a type expression to indicate, for example, that a parameter is not nullable or can accept any type; see the [`@type` tag documentation](tags-type) for details.

 If you provide a description, you can make the JSDoc comment more readable by inserting a hyphen before the description. Be sure to include a space before and after the hyphen.

 Examples
--------

 ### Names, types, and descriptions

 The following examples show how to include names, types, and descriptions in a `@param` tag.

 Name only 
```
/**
 * @param somebody
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}

```
 Name and type 
```
/**
 * @param {string} somebody
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}

```
 Name, type, and description 
```
/**
 * @param {string} somebody Somebody's name.
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}

```
 You can add a hyphen before the description to make it more readable. Be sure to include a space before and after the hyphen.

 Name, type, and description, with a hyphen before the description 
```
/**
 * @param {string} somebody - Somebody's name.
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}

```
 ### Parameters with properties

 If a parameter is expected to have a specific property, you can document that property by providing an additional `@param` tag. For example, if an `employee` parameter is expected to have `name` and `department` properties, you can document it as follows:

 Documenting a parameter's properties 
```
/**
 * Assign the project to an employee.
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function(employee) {
    // ...
};

```
 If a parameter is destructured without an explicit name, you can give the object an appropriate one and document its properties.

 Documenting a destructuring parameter 
```
/**
 * Assign the project to an employee.
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function({ name, department }) {
    // ...
};

```
 You can also combine this syntax with JSDoc's syntax for array parameters. For example, if multiple employees can be assigned to a project:

 Documenting properties of values in an array 
```
/**
 * Assign the project to a list of employees.
 * @param {Object[]} employees - The employees who are responsible for the project.
 * @param {string} employees[].name - The name of an employee.
 * @param {string} employees[].department - The employee's department.
 */
Project.prototype.assign = function(employees) {
    // ...
};

```
 ### Optional parameters and default values

 The following examples show how to indicate that a parameter is optional and has a default value.

 An optional parameter (using JSDoc syntax) 
```
/**
 * @param {string} [somebody] - Somebody's name.
 */
function sayHello(somebody) {
    if (!somebody) {
        somebody = 'John Doe';
    }
    alert('Hello ' + somebody);
}

```
 An optional parameter (using Google Closure Compiler syntax) 
```
/**
 * @param {string=} somebody - Somebody's name.
 */
function sayHello(somebody) {
    if (!somebody) {
        somebody = 'John Doe';
    }
    alert('Hello ' + somebody);
}

```
 An optional parameter and default value 
```
/**
 * @param {string} [somebody=John Doe] - Somebody's name.
 */
function sayHello(somebody) {
    if (!somebody) {
        somebody = 'John Doe';
    }
    alert('Hello ' + somebody);
}

```
 ### Multiple types and repeatable parameters

 The following examples show how to use type expressions to indicate that a parameter can accept multiple types (or any type), and that a parameter can be provided more than once. See the [`@type` tag documentation](tags-type) for details about the type expressions that JSDoc supports.

 Allows one type OR another type (type union) 
```
/**
 * @param {(string|string[])} [somebody=John Doe] - Somebody's name, or an array of names.
 */
function sayHello(somebody) {
    if (!somebody) {
        somebody = 'John Doe';
    } else if (Array.isArray(somebody)) {
        somebody = somebody.join(', ');
    }
    alert('Hello ' + somebody);
}

```
 Allows any type 
```
/**
 * @param {*} somebody - Whatever you want.
 */
function sayHello(somebody) {
    console.log('Hello ' + JSON.stringify(somebody));
}

```
 Allows a parameter to be repeated 
```
/**
 * Returns the sum of all numbers passed to the function.
 * @param {...number} num - A positive or negative number.
 */
function sum(num) {
    var i = 0, n = arguments.length, t = 0;
    for (; i < n; i++) {
        t += arguments[i];
    }
    return t;
}

```
 ### Callback functions

 If a parameter accepts a callback function, you can use the [`@callback` tag](tags-callback) to define a callback type, then include the callback type in the `@param` tag.

 Parameters that accept a callback 
```
/**
 * This callback type is called `requestCallback` and is displayed as a global symbol.
 *
 * @callback requestCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */

/**
 * Does something asynchronously and executes the callback on completion.
 * @param {requestCallback} cb - The callback that handles the response.
 */
function doSomethingAsynchronously(cb) {
    // code
};

```
 Related Links
-------------

 * [@callback](tags-callback)
* [@returns](tags-returns)
* [@type](tags-type)
* [@typedef](tags-typedef)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-param.html>

@private
========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 With the JSDoc tag dictionary (enabled by default):

 `@private`

 With the [Closure Compiler](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#jsdoc-tags) tag dictionary:

 `@private [{typeExpression}]`

 Overview
--------

 The `@private` tag marks a symbol as private, or not meant for general use. Private members are not shown in the generated output unless JSDoc is run with the `-p/--private` command-line option. In JSDoc 3.3.0 and later, you can also use the [`-a/--access` command-line option](about-commandline) to change this behavior.

 The `@private` tag is not inherited by child members. For example, if the `@private` tag is added to a namespace, members of the namespace can still appear in the generated output; because the namespace is private, the members' namepath will not include the namespace.

 The `@private` tag is equivalent to `@access private`.

 Examples
--------

 In the following example, `Documents` and `Documents.Newspaper` appear in the generated documentation, but not `Documents.Diary`.

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

```
 Related Links
-------------

 * [@access](tags-access)
* [@global](tags-global)
* [@instance](tags-instance)
* [@package](tags-package)
* [@protected](tags-protected)
* [@public](tags-public)
* [@static](tags-static)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-private.html>

@property
=========

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Synonyms
--------

  `@prop` 

 Overview
--------

 The @property tag is a way to easily document a list of static properties of a class, namespace or other object.

 Normally JSDoc templates would create an entire new page to display information about each level of a nested namespace hierarchy. Sometimes what you really want is to just list all the properties, including nested properties, all together on the same page.

 Note that property tags must be used in doc comments for the thing that they are properties of, a namespace or a class for example. This tag is intended for simple collections of static properties, it does not allow you to provide @examples or similar complex information for each property, just the type, name and description.

 Examples
--------

 In this example we have a namespace named "config." We want all the information about the defaults property, including its nested values, to appear on the same page with the documentation for config.

 A namespace with defaults and nested default properties 
```
/**
 * @namespace
 * @property {object}  defaults               - The default values for parties.
 * @property {number}  defaults.players       - The default number of players.
 * @property {string}  defaults.level         - The default level for the party.
 * @property {object}  defaults.treasure      - The default treasure.
 * @property {number}  defaults.treasure.gold - How much gold the party starts with.
 */
var config = {
    defaults: {
        players: 1,
        level:   'beginner',
        treasure: {
            gold: 0
        }
    }
};

```
 The following example shows how to indicate that a property is optional.

 A type definition with required and optional property 
```
/**
 * User type definition
 * @typedef {Object} User
 * @property {string} email
 * @property {string} [nickName]
 */

```
 Related Links
-------------

 * [@enum](tags-enum)
* [@member](tags-member)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-property.html>

@protected
==========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 With the JSDoc tag dictionary (enabled by default):

 `@protected`

 With the [Closure Compiler](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#jsdoc-tags) tag dictionary:

 `@protected [{typeExpression}]`

 Overview
--------

 The `@protected` tag marks a symbol as protected. Typically, this tag indicates that a symbol is only available, or should only be used, within the current module.

 By default, symbols marked with the `@protected` tag will appear in your documentation. In JSDoc 3.3.0 and later, you can use the [`-a/--access` command-line option](about-commandline) to change this behavior.

 The `@protected` tag is equivalent to `@access protected`.

 Examples
--------

 In the following example, the instance member `Thingy#_bar` appears in the generated documentation, but with an annotation indicating that it is protected:

 Using the @protected tag 
```
/** @constructor */
function Thingy() {
    /** @protected */
    this._bar = 1;
}

```
 Related Links
-------------

 * [@access](tags-access)
* [@global](tags-global)
* [@instance](tags-instance)
* [@package](tags-package)
* [@private](tags-private)
* [@public](tags-public)
* [@static](tags-static)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-protected.html>

@public
=======

 Table of Contents
-----------------

 * [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Overview
--------

 The `@public` tag indicates that a symbol should be documented as if it were public.

 By default, JSDoc treats all symbols as public, so using this tag does not normally affect the generated documentation. However, you may prefer to use the `@public` tag explicitly so it is clear to others that you intended to make the symbol public.

 In JSDoc 3, the `@public` tag does *not* affect a symbol's scope. Use the [`@instance`](tags-instance), [`@static`](tags-static), and [`@global`](tags-global) tags to change a symbol's scope.

 Examples
--------

 Using the @public tag 
```
/**
 * The Thingy class is available to all.
 * @public
 * @class
 */
function Thingy() {
    /**
     * The Thingy~foo member. Note that 'foo' is still an inner member
     * of 'Thingy', in spite of the @public tag.
     * @public
     */
    var foo = 0;
}

```
 Related Links
-------------

 * [@access](tags-access)
* [@global](tags-global)
* [@instance](tags-instance)
* [@package](tags-package)
* [@private](tags-private)
* [@protected](tags-protected)
* [@static](tags-static)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-public.html>

@readonly
=========

 Table of Contents
-----------------

 * [Overview](#overview)
* [Examples](#examples)

 Overview
--------

 The @readonly tag indicates that a symbol is intended to be read-only. Note this is for the purpose of documentation only - JSDoc won't check whether you've *actually* treated the symbol as read-only in your code.

 Examples
--------

 Using the @readonly tag 
```
/**
 * A constant.
 * @readonly
 * @const {number}
 */
const FOO = 1;

```
 Using the @readonly tag with a getter 
```
/**
 * 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';
    }
};

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-readonly.html>

@requires
=========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)

 Syntax
------

 `@requires <someModuleName>`

 Overview
--------

 The @requires tag allows you to document that a module is needed to use this code. A JSDoc comment can have multiple @require tags. The module name can be specified as "moduleName" or "module:moduleName"; both forms will be interpreted as modules.

 JSDoc does not attempt to process the module that is being included. If you want the module to be included in the documentation, you must include the module in the list of JavaScript files to process.

 Examples
--------

 Using the @requires tag 
```
/**
 * This class requires the modules {@link module:xyzcorp/helper} and
 * {@link module:xyzcorp/helper.ShinyWidget#polish}.
 * @class
 * @requires module:xyzcorp/helper
 * @requires xyzcorp/helper.ShinyWidget#polish
 */
function Widgetizer() {}

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-requires.html>

@returns
========

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Synonyms
--------

  `@return` 

 Syntax
------

 `@returns [{type}] [description]`

 Overview
--------

 The `@returns` tag documents the value that a function returns.

 If you are documenting a generator function, use the [`@yields` tag](tags-yields) instead of this tag.

 Examples
--------

 Return value with a type 
```
/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function sum(a, b) {
    return a + b;
}

```
 Return value with a type and description 
```
/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {number} Sum of a and b
 */
function sum(a, b) {
    return a + b;
}

```
 Return value with multiple types 
```
/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @param {boolean} retArr If set to true, the function will return an array
 * @returns {(number|Array)} Sum of a and b or an array that contains a, b and the sum of a and b.
 */
function sum(a, b, retArr) {
    if (retArr) {
        return [a, b, a + b];
    }
    return a + b;
}

```
 Returns a promise 
```
/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {Promise} Promise object represents the sum of a and b
 */
function sumAsync(a, b) {
    return new Promise(function(resolve, reject) {
        resolve(a + b);
    });
}

```
 Related Links
-------------

 * [@param](tags-param)
* [@yields](tags-yields)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-returns.html>

@see
====

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 * `@see <namepath>`
* `@see <text>`

 Overview
--------

 The @see tag allows you to refer to another symbol or resource that may be related to the one being documented. You can provide either a symbol's namepath or free-form text. If you provide a namepath, JSDoc's default template automatically converts the namepath to a link.

 Examples
--------

 Using the @see tag 
```
/**
 * 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() {}

```
 Related Links
-------------

  [{@link}](tags-inline-link) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-see.html>

@static
=======

 Table of Contents
-----------------

 * [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Overview
--------

 The @static tag indicates that a symbol is contained within a parent and can be accessed without instantiating the parent.

 Using the @static tag will override a symbol's default scope, with one exception: Symbols in global scope will remain global.

 Examples
--------

 The following example has the same effect as writing "@function MyNamespace.myFunction" and omitting the @memberof and @static tags:

 Using @static in a virtual comment 
```
/** @namespace MyNamespace */

/**
 * @function myFunction
 * @memberof MyNamespace
 * @static
 */

```
 The following example forces a module's inner member to be documented as a static member:

 Using @static to override the default scope 
```
/** @module Rollerskate */

/**
 * The 'wheel' variable is documented as Rollerskate.wheel
 * rather than Rollerskate~wheel.
 * @static
 */
var wheel = 1;

```
 Related Links
-------------

 * [@global](tags-global)
* [@inner](tags-inner)
* [@instance](tags-instance)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-static.html>

@summary
========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@summary Summary goes here.`

 Overview
--------

 The @summary tag is a shorter version of the full description. It can be added to any doclet.

 Examples
--------

 
```
/**
 * 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() {}

```
 Related Links
-------------

 * [@classdesc](tags-classdesc)
* [@description](tags-description)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-summary.html>

@throws
=======

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)

 Synonyms
--------

  `@exception` 

 Syntax
------

 * `@throws free-form description`
* `@throws {<type>}`
* `@throws {<type>} free-form description`

 Overview
--------

 The @throws tag allows you to document an error that a function might throw. You can include the @throws tag more than once in a single JSDoc comment.

 Examples
--------

 Using the @throws tag with a type 
```
/**
 * @throws {InvalidArgumentException}
 */
function foo(x) {}

```
 Using the @throws tag with a description 
```
/**
 * @throws Will throw an error if the argument is null.
 */
function bar(x) {}

```
 Using the @throws tag with a type and description 
```
/**
 * @throws {DivideByZero} Argument x must be non-zero.
 */
function baz(x) {}

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-throws.html>

@since
======

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@since <versionDescription>`

 Overview
--------

 The @since tag indicates that a class, method, or other symbol was added in a specific version.

 Examples
--------

 Using the @since tag 
```
/**
 * Provides access to user information.
 * @since 1.0.1
 */
function UserRecord() {}

```
 Related Links
-------------

  [@version](tags-version) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-since.html>

@this
=====

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@this <namePath>`

 Overview
--------

 The @this tag indicates what the `this` keyword refers to when used within another symbol.

 Examples
--------

 In the following example, the @this tag causes "this.name" to be documented as "Greeter#name" rather than a global symbol called "name".

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

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

```
 Related Links
-------------

  [@memberof](tags-memberof) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-this.html>

@todo
=====

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)

 Syntax
------

 `@todo text describing thing to do.`

 Overview
--------

 The @todo tag allows you to document tasks to be completed for some part of your code. You can use the @todo tag more than once in a single JSDoc comment.

 Examples
--------

 Using the @todo tag 
```
/**
 * @todo Write the documentation.
 * @todo Implement this function.
 */
function foo() {
    // write me
}

```


 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-todo.html>

@type
=====

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@type {typeName}`

 Overview
--------

 The @type tag allows you to provide a type expression identifying the type of value that a symbol may contain, or the type of value returned by a function. You can also include type expressions with many other JSDoc tags, such as the [@param tag](tags-param).

 A type expression can include the JSDoc namepath to a symbol (for example, `myNamespace.MyClass`); a built-in JavaScript type (for example, `string`); or a combination of these. You can use any [Google Closure Compiler type expression](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#type-expressions), as well as several other formats that are specific to JSDoc.

 If JSDoc determines that a type expression is invalid, it will display an error and stop running. You can turn this error into a warning by running JSDoc with the `--lenient` option.

 **Note**: Full support for Google Closure Compiler-style type expressions is available in JSDoc 3.2 and later. Earlier versions of JSDoc included partial support for Closure Compiler type expressions.

 Each type is specified by providing a type expression, using one of the formats described below. Where appropriate, JSDoc will automatically create links to the documentation for other symbols. For example, `@type {MyClass}` will link to the MyClass documentation if that symbol has been documented.

 

| Type name | Syntax examples | Description |
| --- | --- | --- |
| Symbol name (name expression) | 
```
{boolean}
{myNamespace.MyClass}

```
 |  Specifies the name of a symbol. If you have documented the symbol, JSDoc creates a link to the documentation for that symbol.  |
|  Multiple types (type union)  | This can be a number or a boolean. 
```
{(number|boolean)}

```
 |  This means a value can have one of several types, with the entire list of types enclosed in parentheses and separated by `|`.  |
|  Arrays and objects (type applications and record types)  | An array of MyClass instances. 
```
{Array.<MyClass>}
// or:
{MyClass[]}

```
 An object with string keys and number values: 
```
{Object.<string, number>}

```
 An object called 'myObj' with properties 'a' (a number), 'b' (a string) and 'c' (any type). 
```
{{a: number, b: string, c}} myObj
// or:
{Object} myObj
{number} myObj.a
{string} myObj.b
{*} myObj.c

```
 |  JSDoc supports Closure Compiler's syntax for defining array and object types. 
 You can also indicate an array by appending `[]` to the type that is contained in the array. For example, the expression `string[]` indicates an array of strings.   For objects that have a known set of properties, you can use Closure Compiler's syntax for documenting record types. You can document each property individually, which enables you to provide more detailed information about each property.  |
|  Nullable type  | A number or null. 
```
{?number}

```
 |  This indicates that the type is either the specified type, or `null`.  |
|  Non-nullable type  | A number, but never null. 
```
{!number}

```
 |  Indicates that the value is of the specified type, but cannot be `null`.  |
|  Variable number of that type  | This function accepts a variable number of numeric parameters. 
```
@param {...number} num

```
 |  Indicates that the function accepts a variable number of parameters, and specifies a type for the parameters. For example:  
```
/**
 * Returns the sum of all numbers passed to the function.
 * @param {...number} num A positive or negative number
 */
function sum(num) {
    var i=0, n=arguments.length, t=0;
    for (; i<n; i++) {
        t += arguments[i];
    }
    return t;
}

```
 |
|  Optional parameter  | An optional parameter named foo. 
```
@param {number} [foo]
// or:
@param {number=} foo

```
 An optional parameter foo with default value 1. 
```
@param {number} [foo=1]

```
 |  Indicates that the parameter is optional. When using JSDoc's syntax for optional parameters, you can also indicate the value that will be used if a parameter is omitted.  |
|  Callbacks  | 
```
/**
 * @callback myCallback
 * @param {number} x - ...
 */

/** @type {myCallback} */
var cb;

```
 |  Document a callback using the [@callback](tags-callback) tag. The syntax is identical to the @typedef tag, except that a callback's type is always "function."  |
|  Type definitions  | Documenting a type with properties 'id', 'name', 'age'. 
```
/**
 * @typedef PropertiesHash
 * @type {object}
 * @property {string} id - an ID.
 * @property {string} name - your name.
 * @property {number} age - your age.
 */

/** @type {PropertiesHash} */
var props;

```
 |  You can document complex types using the [@typedef](tags-typedef) tag, then refer to the type definition elsewhere in your documentation.  |

 Examples
--------

 Example 
```
/** @type {(string|Array.)} */
var foo;
/** @type {number} */
var bar = 1;

```
 In many cases, you can include a type expression as part of another tag, rather than including a separate @type tag in your JSDoc comment.

 Type expressions can accompany many tags. 
```
/**
 * @type {number}
 * @const
 */
var FOO = 1;

// same as:

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

```
 Related Links
-------------

 * [@callback](tags-callback)
* [@typedef](tags-typedef)
* [@param](tags-param)
* [@property](tags-property)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-type.html>

@typedef
========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@typedef [<type>] <namepath>`

 Overview
--------

 The @typedef tag is useful for documenting custom types, particularly if you wish to refer to them repeatedly. These types can then be used within other tags expecting a type, such as [@type](tags-type) or [@param](tags-param).

 Use the [@callback](tags-callback) tag to document the type of callback functions.

 Examples
--------

 This example defines a union type for parameters that can contain either numbers or strings that represent numbers.

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

/**
 * Set the magic number.
 * @param {NumberLike} x - The magic number.
 */
function setMagicNumber(x) {
}

```
 This example defines a more complex type, an object with several properties, and sets its namepath so it will be displayed along with the class that uses the type. Because the type definition is not actually exposed by the class, it is customary to document the type definition as an inner member.

 Using @typedef to document a complex type for a class 
```
/**
 * The complete Triforce, or one or more components of the Triforce.
 * @typedef {Object} WishGranter~Triforce
 * @property {boolean} hasCourage - Indicates whether the Courage component is present.
 * @property {boolean} hasPower - Indicates whether the Power component is present.
 * @property {boolean} hasWisdom - Indicates whether the Wisdom component is present.
 */

/**
 * A class for granting wishes, powered by the Triforce.
 * @class
 * @param {...WishGranter~Triforce} triforce - One to three {@link WishGranter~Triforce} objects
 * containing all three components of the Triforce.
 */
function WishGranter(triforce) {}

```
 Related Links
-------------

 * [@callback](tags-callback)
* [@param](tags-param)
* [@type](tags-type)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-typedef.html>

@variation
==========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 `@variation <variationNumber>`

 Overview
--------

 Sometimes your code may include multiple symbols with the same longname. For example, you might have both a global class and a top-level namespace called `Widget`. In cases such as these, what does "{@link Widget}" or "@memberof Widget" mean? The global namespace, or the global class?

 Variations help JSDoc distinguish between different symbols with the same longname. For example, if "@variation 2" is added to the JSDoc comment for the Widget class, "{@link Widget(2)}" will refer to the class, and "{@link Widget}" will refer to the namespace. Alternatively, you can include the variation when you specify the symbol's with tags such as [@alias](tags-alias) or [@name](tags-name) (for example, "@alias Widget(2)").

 You can provide any value with the @variation tag, as long as the combination of the value and the longname results in a globally unique version of the longname. As a best practice, use a predictable pattern for choosing the values, which will make it easier for you to document your code.

 Examples
--------

 The following example uses the @variation tag to distinguish between the Widget class and the Widget namespace.

 Using the @variation tag 
```
/**
 * The Widget namespace.
 * @namespace Widget
 */

// you can also use '@class Widget(2)' and omit the @variation tag
/**
 * The Widget class. Defaults to the properties in {@link Widget.properties}.
 * @class
 * @variation 2
 * @param {Object} props - Name-value pairs to add to the widget.
 */
function Widget(props) {}

/**
 * Properties added by default to a new {@link Widget(2)} instance.
 */
Widget.properties = {
    /**
     * Indicates whether the widget is shiny.
     */
    shiny: true,
    /**
     * Indicates whether the widget is metallic.
     */
    metallic: true
};

```
 Related Links
-------------

 * [@alias](tags-alias)
* [@name](tags-name)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-variation.html>

@version
========

 Table of Contents
-----------------

 * [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Overview
--------

 Documents the version of an item. The text following the @version tag will be used to denote the version of the item.

 Examples
--------

 Using the @version tag 
```
/**
 * Solves equations of the form a * x = b. Returns the value
 * of x.
 * @version 1.2.3
 * @tutorial solver
 */
function solver(a, b) {
    return b / a;
}

```
 Related Links
-------------

  [@since](tags-since) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-version.html>

@yields
=======

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Synonyms
--------

  `@yield` 

 Syntax
------

 `@yields [{type}] [description]`

 Overview
--------

 The `@yields` tag documents the value that is yielded by a generator function. This tag is available in JSDoc 3.5.0 and later.

 If you are documenting a regular function, use the [`@returns` tag](tags-returns) instead of this tag.

 Examples
--------

 @yields tag with a type 
```
/**
 * Generate the Fibonacci sequence of numbers.
 *
 * @yields {number}
 */
function* fibonacci() {}

```
 @yields tag with a type and description 
```
/**
 * Generate the Fibonacci sequence of numbers.
 *
 * @yields {number} The next number in the Fibonacci sequence.
 */
function* fibonacci() {}

```
 Related Links
-------------

  [@returns](tags-returns) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-yields.html>

{@link}
=======

 Table of Contents
-----------------

 * [Synonyms](#synonyms)
* [Syntax](#syntax)
* [Overview](#overview)
* [Link formatting](#link-formatting)
* [Examples](#examples)
* [Related Links](#related-links)

 Synonyms
--------

 * `{@linkcode}`
* `{@linkplain}`

 Syntax
------

 
```
{@link namepathOrURL}
[link text]{@link namepathOrURL}
{@link namepathOrURL|link text}
{@link namepathOrURL link text (after the first space)}

```
 Overview
--------

 The `{@link}` inline tag creates a link to the namepath or URL that you specify. When you use the `{@link}` tag, you can also provide link text, using one of several different formats. If you don't provide any link text, JSDoc uses the namepath or URL as the link text.

 If you need to link to a tutorial, use the [`{@tutorial}` inline tag](tags-inline-tutorial) instead of the `{@link}` tag.

 Link formatting
---------------

 By default, `{@link}` generates standard HTML anchor tags. However, you may prefer to render certain links in a monospace font, or to specify the format of individual links. You can use the following synonyms for the `{@link}` tag to control the formatting of links:

 * `{@linkcode}`: Forces the link's text to use a monospace font.
* `{@linkplain}`: Forces the link's text to appear as normal text, without a monospace font.

 You can also set one of the following options in JSDoc's configuration file; see [Configuring JSDoc](about-configuring-jsdoc) for more details:

 * `templates.cleverLinks`: When set to `true`, links to URLs use normal text, and links to code use a monospace font.
* `templates.monospaceLinks`: When set to `true`, all links use a monospace font, except for links created with the `{@linkplain}` tag.

 **Note**: Although the default JSDoc template renders all of these tags correctly, other templates may not recognize the `{@linkcode}` and `{@linkplain}` tags. In addition, other templates may ignore the configuration options for link rendering.

 Examples
--------

 The following example shows all of the ways to provide link text for the `{@link}` tag:

 Providing link text 
```
/**
 * 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() {}

```
 By default, the example above produces output similar to the following:

 Output for {@link} tags 
```
See <a href="MyClass.html">MyClass</a> and <a href="MyClass.html#foo">MyClass's foo
property</a>. Also, check out <a href="http://www.google.com">Google</a> and
<a href="https://github.com">GitHub</a>.

```
 If the configuration property `templates.cleverLinks` were set to `true`, the example above would produce the following output:

 Output with clever links enabled 
```
See <a href="MyClass.html"><code>MyClass</code></a> and <a href="MyClass.html#foo">
<code>MyClass's foo property</code></a>. Also, check out
<a href="http://www.google.com">Google</a> and <a href="https://github.com">GitHub</a>.

```
 Related Links
-------------

 * [Configuring JSDoc with a configuration file](about-configuring-jsdoc)
* [Using namepaths with JSDoc 3](about-namepaths)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-inline-link.html>

{@tutorial}
===========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 
```
{@tutorial tutorialID}
[link text]{@tutorial tutorialID}
{@tutorial tutorialID|link text}
{@tutorial tutorialID link text (after the first space)}

```
 Overview
--------

 The `{@tutorial}` inline tag creates a link to the tutorial identifier that you specify. When you use the `{@tutorial}` tag, you can also provide link text, using one of several different formats. If you don't provide any link text, JSDoc uses the tutorial's title as the link text.

 If you need to link to a namepath or a URL, use the [`{@link}` inline tag](tags-inline-link) instead of the `{@tutorial}` tag.

 Examples
--------

 The following example shows all of the ways to provide link text for the `{@tutorial}` tag:

 Providing link text 
```
/**
 * 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() {}

```
 If all of these tutorials are defined, and the title of the `gettingstarted` tutorial is "Getting Started," the example above produces output similar to the following:

 Output for {@link} tags 
```
See <a href="tutorial-gettingstarted.html">Getting Started</a> and
<a href="tutorial-dashboard.html">Configuring the Dashboard</a>.
For more information, see <a href="tutorial-create.html">Creating a Widget</a> and
<a href="tutorial-destroy.html">Destroying a Widget</a>.

```
 Related Links
-------------

  [@tutorial](tags-tutorial) 



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-inline-tutorial.html>

@tutorial
=========

 Table of Contents
-----------------

 * [Syntax](#syntax)
* [Overview](#overview)
* [Examples](#examples)
* [Related Links](#related-links)

 Syntax
------

 
```
@tutorial 

```
 Overview
--------

 The `@tutorial` tag inserts a link to a tutorial file that is provided as part of the documentation. See the [tutorials overview](about-tutorials) for instructions on creating tutorials.

 You can use the `@tutorial` tag more than once in a single JSDoc comment.

 Examples
--------

 In the following example, the documentation for `MyClass` will link to the tutorials that have the identifiers `tutorial-1` and `tutorial-2`:

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

```
 Related Links
-------------

 * [Tutorials](about-tutorials)
* [{@tutorial}](tags-inline-tutorial)
* [@see](tags-see)



 © 2011–2017 the contributors to the JSDoc 3 documentation project  
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.  

<https://jsdoc.app/tags-tutorial.html>

jsdoc