+where ... are paths to other files to generate documentation for.
+
+
Additionally, one may provide the path to a markdown file (ending in ".md") or a file named "README", and this will be added to the documentation on the front page. See these instructions.
+
+
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 given to JSDoc. The command-line options are:
+
+
+
-t, --template <value>
+
+ The name of the template to use for JSDoc's output.
+ The default is the "default" template (JSDoc has another template that comes with it, "haruki").
+
+
-c, --configure <value>
+
+ The path to a configuration file to use to further tailor JSDoc's output (see the Configuration File section).
+ The default is conf.json in the jsdoc executable's directory, or conf.json.EXAMPLE in the same directory if conf.json was not found.
+
+
-e, --encoding <value>
+
+ Assume this encoding when reading all source files. Default: utf8.
+
+
-d, --destination <value>
+
+ The path to the output folder where all the generated documentation will be placed.
+ Use "console" to dump data to the console. Default: ./out/.
+
+
-r, --recurse
+
+ If one of the paths given to jsdoc is a directory, use this flag to recurse into subdirectories when scanning for source code files.
+
+
-u, --tutorials <value>
+
+ Directory in which JSDoc should search for tutorials. If it is not included, no tutorials pages will be generated.
+ See the tutorials instructions for how to add tutorials to your project.
+
+
-p, --private
+
+ By default, symbols marked with the @private tag are not included in the output documentation.
+ If this flag is provided, then they will be.
+
+
-l, --lenient
+
+ By default, if JSDoc encounters an error while parsing and generating documentation, it will halt and display the error to the user.
+ If the lenient flag is provided it will continue to generate output even if this occurs.
+
+
-q, --query <value>
+
+ A query string to parse and store in env.opts.query. Example: "foo=bar&baz=true". TODO: where is this used?
+
+
+
+
The following flags will cause JSDoc to do something else rather than generating documentation:
+
+
+
-X, --explain
+
+ This dumps information about all the doclets found in the files to the console and quits.
+
+
+
-h, --help
+
+ Prints information about all the command-line options and quits.
+
+
+
--version
+
+ Displays JSDoc's version number and quits.
+
+
+
-T, --test
+
+ Runs all JSDoc tests, printing the results to the console, and quits.
+
+
+
+
+
The following options affect JSDoc's behaviour when it is running tests (i.e. the -T or --test option was given):
+
+
+
--verbose
+
+ Display verbose output for tests (write the test names and descriptions to the console).
+
+
+
--match <value>
+
+ Only run tests containing <value>.
+
+
+
--nocolor
+
+ Do not use color in console output from tests.
+
The above will generate documentation for all relevant files found in the src directory, using /path/to/my/conf.json as its configuration file.
+The output documentation will use the Haruki template and be in folder docs (relative to the current directory).
The above will run all of JSDoc's tests that have 'tag' in the title (e.g. '@since tag', '@exports tag'), writing all the test names and descriptions to the console.
To customise JSDoc's behaviour one can provide a configuration file in JSON format to JSDoc using the -c option, e.g. jsdoc -c /path/to/conf.json.
+
+
This file (typically named "conf.json") provides options in JSON format.
+Have a look at "conf.json.EXAMPLE" in the JSDoc directory as a basic example.
+If you do not specify a configuration file, this is what JSDoc will use:
Only files ending in ".js" and ".jsdoc" will be processed (source.includePattern);
+
Any file starting with an underscore or in a directory starting with an underscore will be ignored (source.excludePattern);
+
No plugins are loaded (plugins);
+
@link tags are rendered as-is (i.e. in plain text as opposed to monospace) (templates.cleverLinks, templates.monospaceLinks).
+
+
+
+
+These options and others will be further explained on this page.
+A full example is provided at the end.
+
+
+
Further settings may be added to the file as requested by various plugins or templates (for example, the markdown plugin can be configured by including a "markdown" key).
+
+
Specifying input files
+
+
The "source" set of options, in combination with paths given to JSDoc on the command-line, determine what files JSDoc generates documentation for.
+
+{{#example}}
+ ...
+ "source": {
+ "include": [ /* array of paths to files to generate documentation for */ ],
+ "exclude": [ /* array of paths to exclude */ ],
+ "includePattern": ".+\\.js(doc)?$",
+ "excludePattern": "(^|\\/|\\\\)_"
+ },
+ ...
+{{/example}}
+
+
+
source.include: an optional array of paths that JSDoc should generate documentation for. The paths given to JSDoc on the command line are combined with these to form the set of files JSDoc will scan. Recall that if a path is a directory, the -r option may be used to recurse into it.
+
source.exclude: an optional array of paths that JSDoc should ignore.
+
source.includePattern: an optional string, interpreted as a regular expression. If present, all files must match this in order to be scanned by JSDoc. By default this is set to ".+\.js(doc)?$", meaning that only files that end in .js or .jsdoc will be scanned.
+
source.excludePattern: an optional string, interpreted as a regular expression. If present, any file matching this will be ignored. By default this is set so that files beginning with an underscore (or anything under a directory beginning with an underscore) is ignored.
+
+
+
The order that these options are used in is:
+
+
+
Start with all paths given on the command line and in source.include for files (recall that using the -r command-line option will search within subdirectories).
+
For each file found in Step 1, if the regular expression source.includePattern is present, the file must match it or it is ignored.
+
For each file left from Step 2, if the regular expression source.excludePattern is present, any file matching this is ignored.
+
For each file left from Step 3, if the path is in source.exclude it is ignored.
+
+
+
All remaining files after these four steps are parsed by JSDoc.
+
+
As an example, suppose I have the following file structure:
Based off source.include and the paths given on the command line, we start off with 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)
+
+
Apply source.includePattern, so that we are left with all of the above exceptmyProject/lib/d.txt (as it does not end in ".js" or ".jsdoc").
+
Apply source.excludePattern, which will remove myProject/_private/a.js.
+
Apply source.exclude, which will remove myProject/lib/ignore.js.
+
+
+
+Incorporating command-line options into the configuration file
+
+
+
It is possible to put many of JSDoc's command-line options into the configuration file instead of specifying them on the command-line.
+To do this, use the longnames of the relevant options in an "opts" section of conf.json with the value being the option's value.
+
+{{#example}}opts
+ ...
+ "opts": {
+ "template": "default", // same as -t 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
+ "query": "value", // same as -q value
+ "private": true, // same as -p
+ "lenient": true, // same as -l
+ // these can also be included, though you probably wouldn't bother
+ // putting these in conf.json rather than the command line as they cause
+ // JSDoc not to produce documentation.
+ "version": true, // same as --version
+ "explain": true, // same as -X
+ "test": true, // same as -T
+ "help": true, // same as --help or -h
+ "verbose": true, // same as --verbose, only relevant to tests.
+ "match": "value", // same as --match value, only relevant to tests.
+ "nocolor": true // same as --nocolor, only relevant to tests
+ },
+ ...
+{{/example}}
+
+
Hence between source.include and opts it's possible to put all of jsdoc's arguments in a configuration file so that the command-line reduces to:
If templates.monospaceLinks is true, all link texts from the @link tag 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, it is used and templates.monospaceLinks is ignored.
+
+
Also, there are {@linkcode ...} and {@linkplain ...} if one wishes to force the link to be rendered in monospace or normal font respectively (see @link, @linkcode and @linkplain for further information).
+
+
Miscellaneous
+
+
The tags.allowUnknownTags property determines whether tags unrecognised by JSDoc are permitted.
+If this is false and JSDoc encounters a tag it does not recognise (e.g. @foobar), it will throw an error.
+Otherwise, it will just ignore the tag.
Here is an example conf.json showing all possible configuration options native to the base JSDoc, along with their default values.
+
+{{#example}}A conf.json showcasing all the configuration options to base JSDoc.
+ {
+ "tags": {
+ "allowUnknownTags": true
+ },
+ "source": {
+ "include": [],
+ "exclude": [],
+ "includePattern": ".+\\.js(doc)?$",
+ "excludePattern": "(^|\\/|\\\\)_"
+ },
+ "plugins": [],
+ "templates": {
+ "cleverLinks": false,
+ "monospaceLinks": false
+ },
+ "opts": {
+ "template": "default", // same as -t 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, default "" (no tutorials)
+ "query": "value", // same as -q value, default "" (no query)
+ "private": true, // same as -p
+ "lenient": true, // same as -l
+ // these can also be included, though you probably wouldn't bother
+ // putting these in conf.json rather than the command line as they cause
+ // JSDoc not to produce documentation.
+ "version": true, // same as --version
+ "explain": true, // same as -X
+ "test": true, // same as -T
+ "help": true, // same as --help or -h
+ "verbose": true, // same as --verbose, only relevant to tests.
+ "match": "value", // same as --match value, only relevant to tests.
+ "nocolor": true // same as --nocolor, only relevant to tests
+ },
+ "jsVersion": 180
+ }
+{{/example}}
+
+
+
+where ... are paths to other files to generate documentation for.
+
+
Additionally, one may provide the path to a markdown file (ending in ".md") or a file named "README", and this will be added to the documentation on the front page. See these instructions.
+
+
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 given to JSDoc. The command-line options are:
+
+
+
-t, --template <value>
+
+ The name of the template to use for JSDoc's output.
+ The default is the "default" template (JSDoc has another template that comes with it, "haruki").
+
+
-c, --configure <value>
+
+ The path to a configuration file to use to further tailor JSDoc's output (see the Configuration File section).
+ The default is conf.json in the jsdoc executable's directory, or conf.json.EXAMPLE in the same directory if conf.json was not found.
+
+
-e, --encoding <value>
+
+ Assume this encoding when reading all source files. Default: utf8.
+
+
-d, --destination <value>
+
+ The path to the output folder where all the generated documentation will be placed.
+ Use "console" to dump data to the console. Default: ./out/.
+
+
-r, --recurse
+
+ If one of the paths given to jsdoc is a directory, use this flag to recurse into subdirectories when scanning for source code files.
+
+
-u, --tutorials <value>
+
+ Directory in which JSDoc should search for tutorials. If it is not included, no tutorials pages will be generated.
+ See the tutorials instructions for how to add tutorials to your project.
+
+
-p, --private
+
+ By default, symbols marked with the @private tag are not included in the output documentation.
+ If this flag is provided, then they will be.
+
+
-l, --lenient
+
+ By default, if JSDoc encounters an error while parsing and generating documentation, it will halt and display the error to the user.
+ If the lenient flag is provided it will continue to generate output even if this occurs.
+
+
-q, --query <value>
+
+ A query string to parse and store in env.opts.query. Example: "foo=bar&baz=true". TODO: where is this used?
+
+
+
+
The following flags will cause JSDoc to do something else rather than generating documentation:
+
+
+
-X, --explain
+
+ This dumps information about all the doclets found in the files to the console and quits.
+
+
+
-h, --help
+
+ Prints information about all the command-line options and quits.
+
+
+
--version
+
+ Displays JSDoc's version number and quits.
+
+
+
-T, --test
+
+ Runs all JSDoc tests, printing the results to the console, and quits.
+
+
+
+
+
The following options affect JSDoc's behaviour when it is running tests (i.e. the -T or --test option was given):
+
+
+
--verbose
+
+ Display verbose output for tests (write the test names and descriptions to the console).
+
+
+
--match <value>
+
+ Only run tests containing <value>.
+
+
+
--nocolor
+
+ Do not use color in console output from tests.
+
The above will generate documentation for all relevant files found in the src directory, using /path/to/my/conf.json as its configuration file.
+The output documentation will use the Haruki template and be in folder docs (relative to the current directory).
+
+
+
Another example
+
+
+/path/to/jsdoc -T --match 'tag' --verbose
+
+
+
+
The above will run all of JSDoc's tests that have 'tag' in the title (e.g. '@since tag', '@exports tag'), writing all the test names and descriptions to the console.
To customise JSDoc's behaviour one can provide a configuration file in JSON format to JSDoc using the -c option, e.g. jsdoc -c /path/to/conf.json.
+
+
This file (typically named "conf.json") provides options in JSON format.
+Have a look at "conf.json.EXAMPLE" in the JSDoc directory as a basic example.
+If you do not specify a configuration file, this is what JSDoc will use:
Only files ending in ".js" and ".jsdoc" will be processed (source.includePattern);
+
Any file starting with an underscore or in a directory starting with an underscore will be ignored (source.excludePattern);
+
No plugins are loaded (plugins);
+
@link tags are rendered as-is (i.e. in plain text as opposed to monospace) (templates.cleverLinks, templates.monospaceLinks).
+
+
+
+
+These options and others will be further explained on this page.
+A full example is provided at the end.
+
+
+
Further settings may be added to the file as requested by various plugins or templates (for example, the markdown plugin can be configured by including a "markdown" key).
+
+
Specifying input files
+
+
The "source" set of options, in combination with paths given to JSDoc on the command-line, determine what files JSDoc generates documentation for.
+
+
+
+
+
+...
+"source": {
+ "include": [ /* array of paths to files to generate documentation for */ ],
+ "exclude": [ /* array of paths to exclude */ ],
+ "includePattern": ".+\\.js(doc)?$",
+ "excludePattern": "(^|\\/|\\\\)_"
+},
+...
+
+
+
+
+
source.include: an optional array of paths that JSDoc should generate documentation for. The paths given to JSDoc on the command line are combined with these to form the set of files JSDoc will scan. Recall that if a path is a directory, the -r option may be used to recurse into it.
+
source.exclude: an optional array of paths that JSDoc should ignore.
+
source.includePattern: an optional string, interpreted as a regular expression. If present, all files must match this in order to be scanned by JSDoc. By default this is set to ".+\.js(doc)?$", meaning that only files that end in .js or .jsdoc will be scanned.
+
source.excludePattern: an optional string, interpreted as a regular expression. If present, any file matching this will be ignored. By default this is set so that files beginning with an underscore (or anything under a directory beginning with an underscore) is ignored.
+
+
+
The order that these options are used in is:
+
+
+
Start with all paths given on the command line and in source.include for files (recall that using the -r command-line option will search within subdirectories).
+
For each file found in Step 1, if the regular expression source.includePattern is present, the file must match it or it is ignored.
+
For each file left from Step 2, if the regular expression source.excludePattern is present, any file matching this is ignored.
+
For each file left from Step 3, if the path is in source.exclude it is ignored.
+
+
+
All remaining files after these four steps are parsed by JSDoc.
+
+
As an example, suppose I have the following file structure:
Based off source.include and the paths given on the command line, we start off with 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)
+
+
Apply source.includePattern, so that we are left with all of the above exceptmyProject/lib/d.txt (as it does not end in ".js" or ".jsdoc").
+
Apply source.excludePattern, which will remove myProject/_private/a.js.
+
Apply source.exclude, which will remove myProject/lib/ignore.js.
+
+
+
+Incorporating command-line options into the configuration file
+
+
+
It is possible to put many of JSDoc's command-line options into the configuration file instead of specifying them on the command-line.
+To do this, use the longnames of the relevant options in an "opts" section of conf.json with the value being the option's value.
+
+
+
opts
+
+
+...
+"opts": {
+ "template": "default", // same as -t 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
+ "query": "value", // same as -q value
+ "private": true, // same as -p
+ "lenient": true, // same as -l
+ // these can also be included, though you probably wouldn't bother
+ // putting these in conf.json rather than the command line as they cause
+ // JSDoc not to produce documentation.
+ "version": true, // same as --version
+ "explain": true, // same as -X
+ "test": true, // same as -T
+ "help": true, // same as --help or -h
+ "verbose": true, // same as --verbose, only relevant to tests.
+ "match": "value", // same as --match value, only relevant to tests.
+ "nocolor": true // same as --nocolor, only relevant to tests
+},
+...
+
+
+
+
Hence between source.include and opts it's possible to put all of jsdoc's arguments in a configuration file so that the command-line reduces to:
+
+
+
+
+
+jsdoc -c /path/to/conf.json
+
+
+
+
In the case of options being provided on the command line and in conf.json, the command line takes precedence.
+
+
+
+Plugins
+
+
To enable plugins, add their paths (relative to the JSDoc folder) into the plugins array.
+
+
For example, the following will include the Markdown plugin and verbose output plugin:
If templates.monospaceLinks is true, all link texts from the @link tag 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, it is used and templates.monospaceLinks is ignored.
+
+
Also, there are {@linkcode ...} and {@linkplain ...} if one wishes to force the link to be rendered in monospace or normal font respectively (see @link, @linkcode and @linkplain for further information).
+
+
Miscellaneous
+
+
The tags.allowUnknownTags property determines whether tags unrecognised by JSDoc are permitted.
+If this is false and JSDoc encounters a tag it does not recognise (e.g. @foobar), it will throw an error.
+Otherwise, it will just ignore the tag.
Here is an example conf.json showing all possible configuration options native to the base JSDoc, along with their default values.
+
+
+
A conf.json showcasing all the configuration options to base JSDoc.
+
+
+{
+ "tags": {
+ "allowUnknownTags": true
+ },
+ "source": {
+ "include": [],
+ "exclude": [],
+ "includePattern": ".+\\.js(doc)?$",
+ "excludePattern": "(^|\\/|\\\\)_"
+ },
+ "plugins": [],
+ "templates": {
+ "cleverLinks": false,
+ "monospaceLinks": false
+ },
+ "opts": {
+ "template": "default", // same as -t 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, default "" (no tutorials)
+ "query": "value", // same as -q value, default "" (no query)
+ "private": true, // same as -p
+ "lenient": true, // same as -l
+ // these can also be included, though you probably wouldn't bother
+ // putting these in conf.json rather than the command line as they cause
+ // JSDoc not to produce documentation.
+ "version": true, // same as --version
+ "explain": true, // same as -X
+ "test": true, // same as -T
+ "help": true, // same as --help or -h
+ "verbose": true, // same as --verbose, only relevant to tests.
+ "match": "value", // same as --match value, only relevant to tests.
+ "nocolor": true // same as --nocolor, only relevant to tests
+ },
+ "jsVersion": 180
+}
+
+