From 5000da334c351bafe838eb2216b4ddae32b43ba7 Mon Sep 17 00:00:00 2001 From: mathematicalcoffee Date: Thu, 31 Jan 2013 16:49:21 +1000 Subject: [PATCH 1/3] added page for command-line options --- Jake/articles/about-commandline | 132 +++++++++++++ about-commandline.html | 329 ++++++++++++++++++++++++++++++++ 2 files changed, 461 insertions(+) create mode 100644 Jake/articles/about-commandline create mode 100644 about-commandline.html diff --git a/Jake/articles/about-commandline b/Jake/articles/about-commandline new file mode 100644 index 00000000..3a885628 --- /dev/null +++ b/Jake/articles/about-commandline @@ -0,0 +1,132 @@ + +

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

+ +{{#example}} +/path/to/jsdoc yourSourceCodeFile.js anotherSourceCodeFile.js ... +{{/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. +
+ +
+ +

Examples

+{{#example}}Example +/path/to/jsdoc src -r -t haruki -c /path/to/my/conf.json -d docs +{{/example}} + +

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).

+ +{{#example}}Another example +/path/to/jsdoc -T --match 'tag' --verbose +{{/example}} + +

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

+ + + diff --git a/about-commandline.html b/about-commandline.html new file mode 100644 index 00000000..1d06475a --- /dev/null +++ b/about-commandline.html @@ -0,0 +1,329 @@ + + + + + Use JSDoc: Command-line arguments to JSDoc + + + + + + + + + + +
+ @use JSDoc +
+ + + +
+

Command-line arguments to JSDoc

+ +

+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/. +
+
-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. +
+ +
+ +

Examples

+
+
Example
+
+
+/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

+ + + + +
+ + + + + + From d7a7a8e694649bb8bb03ba6b3ff9cc2070996dbb Mon Sep 17 00:00:00 2001 From: mathematicalcoffee Date: Thu, 31 Jan 2013 16:49:36 +1000 Subject: [PATCH 2/3] added page for conf.json --- Jake/articles/about-configuring-jsdoc | 305 +++++++++++++++ about-configuring-jsdoc.html | 534 ++++++++++++++++++++++++++ 2 files changed, 839 insertions(+) create mode 100644 Jake/articles/about-configuring-jsdoc create mode 100644 about-configuring-jsdoc.html diff --git a/Jake/articles/about-configuring-jsdoc b/Jake/articles/about-configuring-jsdoc new file mode 100644 index 00000000..9f2673a2 --- /dev/null +++ b/Jake/articles/about-configuring-jsdoc @@ -0,0 +1,305 @@ + +

Table of Contents

+ + + +

Configuration File

+ +

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:

+ +{{#example}}conf.json.EXAMPLE +{ + "tags": { + "allowUnknownTags": true + }, + "source": { + "includePattern": ".+\\.js(doc)?$", + "excludePattern": "(^|\\/|\\\\)_" + }, + "plugins": [], + "templates": { + "cleverLinks": false, + "monospaceLinks": false + }, + "jsVersion": 180 +} +{{/example}} +

This means: +

+

+ +

+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}} + + + +

The order that these options are used in is:

+ +
    +
  1. 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).
    2. +
  2. For each file found in Step 1, if the regular expression source.includePattern is present, the file must match it or it is ignored.
    3. +
  3. For each file left from Step 2, if the regular expression source.excludePattern is present, any file matching this is ignored.
    4. +
  4. For each file left from Step 3, if the path is in source.exclude it is ignored.
    5. +
+ +

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

+ +

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

+ +{{#example}} +myProject/ +|- a.js +|- b.js +|- c.js +|- _private +| |- a.js +|- lib/ + |- a.js + |- ignore.js + |- d.txt +{{/example}} + +

And I set the "source" part of my conf.json like so:

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

If I run JSDoc like this from the file containing the myProject folder:

+ +{{#example}} +jsdoc myProject/c.js -c /path/to/my/conf.json -r +{{/example}} + +

Then JSDoc will make documentation for the files:

+ + + +

The reasoning is as follows:

+ +
    +
  1. 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)
      • +
    2. +
  2. Apply source.includePattern, so that we are left with all of the above except myProject/lib/d.txt (as it does not end in ".js" or ".jsdoc").
    3. +
  3. Apply source.excludePattern, which will remove myProject/_private/a.js.
    4. +
  4. Apply source.exclude, which will remove myProject/lib/ignore.js.
    5. +
+ +

+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:

+ +{{#example}} + jsdoc -c /path/to/conf.json +{{/example}} + +

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:

+ +{{#example}} + ... + "plugins": [ + "plugins/markdown", + "plugins/verboseOutput" + ] + ... +{{/example}} + +

See the plugin reference for further information, and look in jsdoc/plugins for the plugins built-in to JSDoc.

+ +

The Markdown plugin can be configured by including a "markdown" object into conf.json; see Configuring the Markdown Plugin for further information.

+ +

Output style configuration

+ +

The options in templates affect how JSDoc's output looks (although custom templates may not be affected by these, depending on how they are coded).

+ +{{#example}} + ... + "templates": { + "cleverLinks": false, + "monospaceLinks": false + }, + ... +{{/example}} + +

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.

+ +

By default, it is true.

+ +{{#example}} + ... + "tags": { + "allowUnknownTags": true + }, + ... +{{/example}} + +

The tags.jsVersion tag should be left as-is.

+ +

+Example with all configuration options +

+ +

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}} + + +

See Also

+ + + diff --git a/about-configuring-jsdoc.html b/about-configuring-jsdoc.html new file mode 100644 index 00000000..497f041a --- /dev/null +++ b/about-configuring-jsdoc.html @@ -0,0 +1,534 @@ + + + + + Use JSDoc: Configuring JSDoc with conf.json + + + + + + + + + + +
+ @use JSDoc +
+ + + +
+

Configuring JSDoc with conf.json

+ +

Table of Contents

+ + + +

Configuration File

+ +

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:

+ +
+
conf.json.EXAMPLE
+
+
+{
+    "tags": {
+        "allowUnknownTags": true
+    },
+    "source": {
+        "includePattern": ".+\\.js(doc)?$",
+        "excludePattern": "(^|\\/|\\\\)_"
+    },
+    "plugins": [],
+    "templates": {
+        "cleverLinks": false,
+        "monospaceLinks": false
+    },
+    "jsVersion": 180
+}
+
+
+
+

This means: +

    +
  • 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:

+ +
    +
  1. 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).
    2. +
  2. For each file found in Step 1, if the regular expression source.includePattern is present, the file must match it or it is ignored.
    3. +
  3. For each file left from Step 2, if the regular expression source.excludePattern is present, any file matching this is ignored.
    4. +
  4. For each file left from Step 3, if the path is in source.exclude it is ignored.
    5. +
+ +

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

+ +

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

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

And I set the "source" part of my conf.json like so:

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

If I run JSDoc like this from the file containing the myProject folder:

+ +
+
+
+
+jsdoc myProject/c.js -c /path/to/my/conf.json -r
+
+
+
+

Then JSDoc will make documentation for the files:

+ +
    +
  • myProject/a.js
    • +
  • myProject/c.js
    • +
  • myProject/lib/a.js
    • +
+ +

The reasoning is as follows:

+ +
    +
  1. 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)
      • +
    2. +
  2. Apply source.includePattern, so that we are left with all of the above except myProject/lib/d.txt (as it does not end in ".js" or ".jsdoc").
    3. +
  3. Apply source.excludePattern, which will remove myProject/_private/a.js.
    4. +
  4. Apply source.exclude, which will remove myProject/lib/ignore.js.
    5. +
+ +

+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:

+ +
+
+
+
+...
+"plugins": [
+    "plugins/markdown",
+    "plugins/verboseOutput"
+]
+...
+
+
+
+

See the plugin reference for further information, and look in jsdoc/plugins for the plugins built-in to JSDoc.

+ +

The Markdown plugin can be configured by including a "markdown" object into conf.json; see Configuring the Markdown Plugin for further information.

+ +

Output style configuration

+ +

The options in templates affect how JSDoc's output looks (although custom templates may not be affected by these, depending on how they are coded).

+ +
+
+
+
+...
+"templates": {
+    "cleverLinks": false,
+    "monospaceLinks": false
+},
+...
+
+
+
+

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.

+ +

By default, it is true.

+ +
+
+
+
+...
+"tags": {
+    "allowUnknownTags": true
+},
+...
+
+
+
+

The tags.jsVersion tag should be left as-is.

+ +

+Example with all configuration options +

+ +

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
+}
+
+
+
+

See Also

+ + + + +
+ + + + + + From 55160b6765c4908ba0282c1b0f5fb20bcef877b9 Mon Sep 17 00:00:00 2001 From: mathematicalcoffee Date: Thu, 31 Jan 2013 16:49:54 +1000 Subject: [PATCH 3/3] added command-line and conf.json pages to the index --- Jake/articles/index | 4 ++ index.html | 112 +++++++++++++++++++++++++------------------- 2 files changed, 67 insertions(+), 49 deletions(-) diff --git a/Jake/articles/index b/Jake/articles/index index 9f2b54d5..58b6887e 100644 --- a/Jake/articles/index +++ b/Jake/articles/index @@ -36,6 +36,10 @@
Additional longtext tutorials for your code.
Adding Content to Index.html
Using Readme files to add content to the default index.html
+
Command-line options to JSDoc 3
+
About the command-line options JSDoc supports.
+
Configuring JSDoc 3 with conf.json
+
How to configure JSDoc's output with a configuration file.
All about plugins
Installing plugins and writing your own.
Configuring the markdown plugin
diff --git a/index.html b/index.html index dbae8157..8d5c0055 100644 --- a/index.html +++ b/index.html @@ -209,6 +209,10 @@

Getting Started

Additional longtext tutorials for your code.
Adding Content to Index.html
Using Readme files to add content to the default index.html
+
Command-line options to JSDoc 3
+
About the command-line options JSDoc supports.
+
Configuring JSDoc 3 with conf.json
+
How to configure JSDoc's output with a configuration file.
All about plugins
Installing plugins and writing your own.
Configuring the markdown plugin
@@ -235,57 +239,67 @@

Contribute

JSDoc 3 Tag Dictionary

-
@augments
-
This object adds onto a parent object.
@author
-
Documents the author of an item.
@borrows
-
This object uses something from another object.
@callback
-
Document a callback function.
@classdesc
-
Use the following text to describe the entire class.
@constant
-
Document an object as a constant.
@constructor
-
This function is intended to be called with the "new" keyword.
@constructs
-
This function member will be the constructor for the previous class.
@copyright
-
Document some copyright information.
@default
-
Document the default value.
@deprecated
-
Document that this is no longer the preferred way.
@desc
-
Describe the object.
@enum
-
Document a collection of related properties.
@event
-
Document an event.
@example
-
Provide an example of how to use a documented item.
@exports
-
Document the name of a JavaScript module.
@file
-
Describe a file.
@fires
-
Describe the events this method may fire.
@global
-
Document a global object.
@ignore
+
@event
+
Document an event.
@deprecated
+
Document that this is no longer the preferred way.
@mixes
+
[todo] This object mixes in all the members from another object.
@constant
+
Document an object as a constant.
@summary
+
[todo] A shorter version of the full description.
@abstract
+
This member is meant to be abstract.
@memberof
+
[todo] This object is a member or another object.
@constructor
+
This function is intended to be called with the "new" keyword.
@tagname
+
[todo]
@requires
+
[todo] This JavaScript module requires another JavaScript module.
@version
+
Documents the version number of an item.
@throws
+
[todo] Describe what errors could be thrown.
@classdesc
+
Use the following text to describe the entire class.
@author
+
Documents the author of an item.
@kind
+
[todo] What kind of object is this?
@member
+
[todo] Document a member.
@since
+
[todo] When was this feature added?
@access
+
Specify the access level of this member - private, public, or protected.
@borrows
+
This object uses something from another object.
@mixin
+
[todo] Document a mix-in object.
@see
+
[todo] Refer to some other documentation for more information.
@tagname
+
[todo]
@file
+
Describe a file.
@example
+
Provide an example of how to use a documented item.
@tutorial
+
Insert a link to an included tutorial file.
@license
+
[todo] Document the software license that applies to this code.
@fires
+
Describe the events this method may fire.
@callback
+
Document a callback function.
@module
+
[todo] Document a JavaScript module.
@protected
+
[todo] This member is meant to be protected.
@typedef
+
[todo] Document a custom type.
@global
+
Document a global object.
@public
+
[todo] This member is meant to be public.
@this
+
[todo] What does the this keyword refer to here?
@readonly
+
[todo] This variable is meant to be readonly.
@augments
+
This object adds onto a parent object.
@type
+
[todo] Document the type of an object.
@tagname
+
[todo]
@tagname
+
[todo]
@exports
+
Document the name of a JavaScript module.
@constructs
+
This function member will be the constructor for the previous class.
@ignore
[todo] Remove this from the final output.
@inner
-
[todo] Document an inner object.
@instance
-
[todo] Document an instance member.
@kind
-
[todo] What kind of object is this?
@license
-
[todo] Document the software license that applies to this code.
@member
-
[todo] Document a member.
@memberof
-
[todo] This object is a member or another object.
@method
-
[todo] Describe a method or function.
@mixes
-
[todo] This object mixes in all the members from another object.
@mixin
-
[todo] Document a mix-in object.
@module
-
[todo] Document a JavaScript module.
@name
+
[todo] Document an inner object.
@todo
+
[todo] Document tasks to be completed for an object.
@property
+
Document a property of an object.
@returns
+
Document the return value of a function.
@static
+
Document a static member.
@param
+
>Document the parameter to a function.
@copyright
+
Document some copyright information.
@desc
+
Describe the object.
@instance
+
[todo] Document an instance member.
@external
+
[todo]
@name
[todo] Document the name of an object.
@namespace
-
[todo] Document a namespace object.
@param
-
>Document the parameter to a function.
@private
-
[todo] This member is meant to be private.
@property
-
Document a property of an object.
@protected
-
[todo] This member is meant to be protected.
@public
-
[todo] This member is meant to be public.
@readonly
-
[todo] This variable is meant to be readonly.
@requires
-
[todo] This JavaScript module requires another JavaScript module.
@returns
-
Document the return value of a function.
@see
-
[todo] Refer to some other documentation for more information.
@since
-
[todo] When was this feature added?
@summary
-
[todo] A shorter version of the full description.
@this
-
[todo] What does the this keyword refer to here?
@throws
-
[todo] Describe what errors could be thrown.
@todo
-
[todo] Document tasks to be completed for an object.
@tutorial
-
Insert a link to an included tutorial file.
@type
-
[todo] Document the type of an object.
@typedef
-
[todo] Document a custom type.
@version
-
Documents the version number of an item.
+
[todo] Document a namespace object.
@enum
+
Document a collection of related properties.
@default
+
Document the default value.
@tagname
+
[todo]
@tagname
+
[todo]
@private
+
[todo] This member is meant to be private.
@method
+
[todo] Describe a method or function.