Command-line arguments to JSDoc
At its most basic level, JSDoc is used like so:
/path/to/jsdoc yourSourceCodeFile.js anotherSourceCodeFile.js ...
... 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:
- 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").
The path to a configuration file to use to further tailor JSDoc's output (see the Configuration File section).
The default is
jsdocexecutable's directory, or
conf.json.EXAMPLEin the same directory if
conf.jsonwas not found.
- Assume this encoding when reading all source files. Default: utf8.
The path to the output folder where all the generated documentation will be placed.
Use "console" to dump data to the console. Default:
If one of the paths given to
jsdocis a directory, use this flag to recurse into subdirectories when scanning for source code files.
- 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.
- 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
--test option was given):
- Display verbose output for tests (write the test names and descriptions to the console).
Only run tests containing
- 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.