added page for command-line options

Author: mathematicalcoffee

Jake/articles/about-commandline

@@ -0,0 +1,132 @@
+<!--{
+    title:       'Command-line arguments to JSDoc',
+    out:         'about-commandline.html',
+    description: 'About command-line arguments to JSDoc.'
+}-->
+<p>
+At its most basic level, JSDoc is used like so:
+</p>
+
+{{#example}} 
+/path/to/jsdoc yourSourceCodeFile.js anotherSourceCodeFile.js ...
+{{/example}}
+
+<p>
+where <code>...</code> are paths to other files to generate documentation for.</p>
+
+<p>Additionally, one may provide the path to a <a href="http://daringfireball.net/projects/markdown/">markdown file</a> (ending in ".md") or a file named "README", and this will be added to the documentation on the front page. See <a href="about-including-readme.html">these instructions</a>.</p>
+
+<p>JSDoc supports a number of command-line options, many of which have both long and short forms.
+Alternatively, the command-line options may be<a href="about-configuring-jsdoc.html#TODO"> specified in a configuration file</a> given to JSDoc. The command-line options are:</p>
+
+<dl>
+  <dt><code>-t</code>, <code>--template &lt;value&gt;</code></dt>
+    <dd>
+      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").
+    </dd>
+  <dt><code>-c</code>, <code>--configure &lt;value&gt;</code></dt>
+    <dd>
+      The path to a configuration file to use to further tailor JSDoc's output (see the <a href="#configuration-file">Configuration File</a> section).
+      The default is <code>conf.json</code> in the <code>jsdoc</code> executable's directory, or <code>conf.json.EXAMPLE</code> in the same directory if <code>conf.json</code> was not found.
+    </dd>
+  <dt><code>-e</code>, <code>--encoding &lt;value&gt;</code></dt>
+    <dd>
+      Assume this encoding when reading all source files. Default: utf8.
+    </dd>
+  <dt><code>-d</code>, <code>--destination &lt;value&gt;</code></dt>
+    <dd>
+      The path to the output folder where all the generated documentation will be placed.
+      Use "console" to dump data to the console. Default: <code>./out/</code>.
+    </dd>
+  <dt><code>-r</code>, <code>--recurse</code></dt>
+    <dd>
+      If one of the paths given to <code>jsdoc</code> is a directory, use this flag to recurse into subdirectories when scanning for source code files.
+    </dd>
+  <dt><code>-u</code>, <code>--tutorials &lt;value&gt;</code></dt>
+    <dd>
+      Directory in which JSDoc should search for tutorials. If it is not included, no tutorials pages will be generated.
+      See the <a href="about-tutorials.html">tutorials instructions</a> for how to add tutorials to your project.
+    </dd>
+  <dt><code>-p</code>, <code>--private</code></dt>
+    <dd>
+      By default, symbols marked with the <a href="tags-private.html">@private</a> tag are not included in the output documentation.
+      If this flag is provided, then they will be.
+    </dd>
+  <dt><code>-l</code>, <code>--lenient</code></dt>
+    <dd>
+      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.
+    </dd>
+  <dt><code>-q</code>, <code>--query &lt;value&gt;</code></dt>
+    <dd>
+      A query string to parse and store in env.opts.query. Example: "foo=bar&amp;baz=true". TODO: where is this used?
+    </dd>
+</dl>
+
+<p>The following flags will cause JSDoc to do something else rather than generating documentation:</p>
+
+<dl>
+  <dt><code>-X</code>, <code>--explain</code></dt>
+    <dd>
+     This dumps information about all the doclets found in the files to the console and quits.
+    </dd>
+  </dt>
+  <dt><code>-h</code>, <code>--help</code></dt>
+    <dd>
+      Prints information about all the command-line options and quits.
+    </dd>
+  </dt>
+  <dt><code>--version</code></dt>
+    <dd>
+      Displays JSDoc's version number and quits.
+    </dd>
+  </dt>
+  <dt><code>-T</code>, <code>--test</code></dt>
+    <dd>
+      Runs all JSDoc tests, printing the results to the console, and quits.
+    </dd>
+  </dt>
+</dl>
+
+<p>The following options affect JSDoc's behaviour when it is running tests (i.e. the <code>-T</code> or <code>--test</code> option was given):</p>
+
+<dl>
+  <dt><code>--verbose</code></dt>
+    <dd>
+      Display verbose output for tests (write the test names and descriptions to the console).
+    </dd>
+  </dt>
+  <dt><code>--match &lt;value&gt;</code></dt>
+    <dd>
+      Only run tests containing <code>&lt;value&gt;</code>.
+    </dd>
+  </dt>
+  <dt><code>--nocolor</code></dt>
+    <dd>
+      Do not use color in console output from tests.
+    </dd>
+  </dt>
+</dl>
+
+<h2>Examples</h2>
+{{#example}}Example
+/path/to/jsdoc src -r -t haruki -c /path/to/my/conf.json -d docs
+{{/example}}
+
+<p>The above will generate documentation for all relevant files found in the <code>src</code> directory, using <code>/path/to/my/conf.json</code> as its configuration file.
+The output documentation will use the Haruki template and be in folder <code>docs</code> (relative to the current directory).</p>
+
+{{#example}}Another example
+/path/to/jsdoc -T --match 'tag' --verbose
+{{/example}}
+
+<p>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.</p>
+
+<h2 id="see-also" name="see-also">See Also</h2>
+
+<ul>
+<li><a href="about-configuring-jsdoc.html#configuration-file-command-line">Specifying command-line options for JSDoc in the configuration file</a></li>
+<li><a href="about-testing-jsdoc3.html">Running JSDoc's tests</a></li>
+</ul>
+