Command-line arguments to JSDoc

May 18, 2022 0 Comments

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 (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/.
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.
By default, symbols marked with the @private tag are not included in the output documentation. If this flag is provided, then they will be.
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:

This dumps information about all the doclets found in the files to the console and quits.
Prints information about all the command-line options and quits.
Displays JSDoc’s version number and quits.
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):

Display verbose output for tests (write the test names and descriptions to the console).
--match <value>
Only run tests containing <value>.
Do not use color in console output from tests.


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

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.

See Also

  • Specifying command-line options for JSDoc in the configuration file
  • Running JSDoc’s tests