about-jsdoc3.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    
    <meta name="description" content="Usage instructions and basic info about JSDoc 3">
    
    
    <title>Use JSDoc: Readme</title>
    
    <link rel="stylesheet" href="lib/desert.css" />
    <script src="lib/prettify.js"></script>
    
    <script type="text/javascript">
        /* Make HTML 5 elements stylable in IE */
        document.createElement('header');
        document.createElement('nav');
        document.createElement('article');
        document.createElement('footer');
        document.createElement('hgroup');
    </script>
    
    <style>
        body 
        {
            font: 1em 'Helvetica Neue', Helvetica, Arial, sans-serif;
            padding: 0;
            margin: 0;
        }
        
        a, a:visited, a:active 
        {
            color: #605C89;
        }
        
        /* Make HTML 5 elements display block-level for consistent styling */
        header, nav, article, footer, address 
        {
            display: block;
        }
        
        header
        {
            background-color: #EBEBEB;
            color: #006FBB;
            margin: 0;
            margin-bottom: 32px;
            padding: 18px;
            font-size: 2.4em;
            font-weight: bold;
            border-bottom: 1px #C6C6C6 solid;
        }
        
        header a, header a:visited 
        {
            color: #006FBB;
            text-decoration: none;
        }
        
        article 
        {
            margin: 18px;
        }
        
        footer
        {
            margin: 16px;
            margin-top: 32px;
            font-style: italic;
            font-size: 0.8em;
        }
        
        h1, h2, h3, h4, h5, h6
        {
            color: #B93A38;
        }
        
        h1
        {
            font-size: 1.428em;
            text-indent: 0;
        }

        h2
        {
            font-size: 1.285em;
            text-indent: 1%;
        }

        h3
        {
            font-size: 1.142em;
            text-indent: 2%;
        }

        h4
        {
            font-size: 1em;
            text-indent: 3%;
        }

        h5
        {
            font-size: 0.857em;
            text-indent: 4%;
        }

        h6
        {
            font-size: 0.714em;
            text-indent: 5%;
        }
        
        p
        {
            text-indent: 2%;
        }
        
        dl
        {
            margin-left: 2%;
            padding-left: 0;
        }
        
        dt
        {
            margin-left: 16px;
            padding-left: 4px;
            margin-top: 8px;
        }
        
        dt a, dt a:visited 
        {
            color: #3E00B6;
        }
        
        dd
        {
            margin-left: 16px;
            padding-left: 4px;
        }
        
        ol, ul
        {
            margin-left: 2%;
        }
        
        code 
        {
            font: 1em Consolas, "Lucida Console", Monaco, monospace;
            background-color: #DEDEDE;
        }
        
        pre
        {
            display: block;
            border: 1px solid #999;
            margin: 12px;
            padding: 8px;
            white-space: pre-wrap;
            background-color: #333333;
            color: #03FF00;
        }
        
        .example dt 
        {
            font-weight: bold;
        }
        
        .tags-definition {
            margin: 0px 1%;
        }
        
        .tags-definition th {
            text-align: left;
            vertical-align: top;
            font-weight: 800;
            background-color: gold;
        }
        
        .tags-definition td {
            text-align: left;
            vertical-align: top;
        }

    </style>
</head>

<body>
    <header>
        <a href="./index.html">@use JSDoc</a><br>
        <span style="font-size: 0.5em; margin-left: 6%;"><a href="http://usejsdoc.org/index.html">The best documentation tool for JavaScript, ever.&trade;</a></span>
    </header>
    
    <nav>
    </nav>
    
    <article>
    <h1>Readme</h1>
    

<div class="about-overview" id="jsdoc3-overview">
<p>
    An inline API documentation processor for JavaScript. JSDoc 3 is intended to be an upgrade to JsDoc Toolkit (JSDoc 2).
</p>

<h3>
    Pull Requesters: Please read HOW<em>TO</em>CONTRIBUTE.md
</h3>

<h2>
    Installation
</h2>

<p>
    Download a copy of JSDoc 3 from the official Git Hub repository here: <a href="https://github.com/jsdoc3/jsdoc">https://github.com/jsdoc3/jsdoc</a>
</p>

<p>
    To test that jsdoc is working, change your working directory to the jsdoc folder and run the following command on Windows:
</p>

<p>
    <b>Example</b>
</p>

<dl class="example">
<dt></dt>
<dd>
<pre class="prettyprint linenums">
jsdoc -T

</pre>
</dd>
</dl>
<p>
    ... or on a Max OSX or *nix platform:
</p>

<p>
    <b>Example</b>
</p>

<dl class="example">
<dt></dt>
<dd>
<pre class="prettyprint linenums">
./jsdoc -T

</pre>
</dd>
</dl>
<p>
    If you can't get the short-form commands to work, try invoking Java directly:
</p>

<p>
    <b>Example</b>
</p>

<dl class="example">
<dt></dt>
<dd>
<pre class="prettyprint linenums">
java -cp lib/js.jar org.mozilla.javascript.tools.shell.Main \
-modules nodejs_modules -modules rhino_modules -modules . \
jsdoc.js -T

</pre>
</dd>
</dl>
<h2>
    Usage
</h2>

<p>
    This example assumes that your working directory is the jsdoc application base directory:
</p>

<p>
    <b>Example</b>
</p>

<dl class="example">
<dt></dt>
<dd>
<pre class="prettyprint linenums">
./jsdoc yourSourceCodeFile.js

</pre>
</dd>
</dl>
<p>
    For help regarding the supported commandline options use the --help option.
</p>

<p>
    <b>Example</b>
</p>

<dl class="example">
<dt></dt>
<dd>
<pre class="prettyprint linenums">
./jsdoc --help

</pre>
</dd>
</dl>
<p>
    Generated documentation will appear in the folder specified by the --destination option, or in a folder named "out" by default.
</p>

<h2>
    Dependencies
</h2>

<p>
    JSDoc 3 utilises the Mozilla Rhino engine, which requires Java. JSDoc 3 is known to work with version 1.6.0_24 of Java.
</p>

<p>
    JSDoc 3 uses advanced features in the Rhino application which are only available in or after the 1.7 release 3. A copy of this version of Rhino is included in JSDoc so this is not normally an issue that the user needs to be concerned with. However, in rare cases, users may have their Java CLASSPATH configured to override that included Rhino and point to some older version of Rhino instead. If this is the case, simply correct the CLASSPATH to remove the older Rhino.
</p>

<p>
    The version of rhino distributed with JSDoc 3 can be found here: https://github.com/jannon/rhino
</p>

<h2>
    Debugging
</h2>

<p>
    Rhino is not always very friendly when it comes to reporting errors in JavaScript. Luckily it comes with a full-on debugger included that can be much more useful than a simple stack trace. To invoke JSDoc with the debugger try the following command:
</p>

<p>
    <b>Example</b>
</p>

<dl class="example">
<dt></dt>
<dd>
<pre class="prettyprint linenums">
jsdoc --debug

</pre>
</dd>
</dl>
<p>
    or the long form version:
</p>

<p>
    <b>Example</b>
</p>

<dl class="example">
<dt></dt>
<dd>
<pre class="prettyprint linenums">
$ java -classpath lib/js.jar \
org.mozilla.javascript.tools.debugger.Main -debug \
-modules nodejs_modules -modules rhino_modules -modules . \
jsdoc.js \
your/script.js

</pre>
</dd>
</dl>
<p>
    Note: <code>--debug</code> must be the first argument to the short form command
</p>

<p>
    This will open a debugging window. Choose "Break on Exceptions" from the "Debug" menu, then press the "Run" button. If there is an error, you should see exactly where it is in the source code.
</p>

<h2>
    See Also
</h2>

<p>
    <br>
    Project Documentation: <a href="http://usejsdoc.org/">http://usejsdoc.org/</a> (under development)
    <br>
    Project Documentation Source: <a href="https://github.com/micmath/micmath.github.com">https://github.com/micmath/micmath.github.com</a>
    <br>
    JSDoc User's Group: <a href="http://groups.google.com/group/jsdoc-users">http://groups.google.com/group/jsdoc-users</a>
    <br>
    JSDoc 3 Ant Task <a href="https://github.com/jannon/jsdoc3-ant-task">https://github.com/jannon/jsdoc3-ant-task</a>
    <br>
    Project Announcemnts: <a href="http://twitter.com/jsdoc3">http://twitter.com/jsdoc3</a>
</p>

<h2>
    License
</h2>

<p>
    JSDoc 3 is copyright (c) 2011 Michael Mathews <a href="mailto:micmath@gmail.com">micmath@gmail.com</a>
</p>

<p>
    See file "LICENSE.md" in this distribution for more details about terms of use.
</p>
</div>
    </article>
    
    <footer>
        <img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-sa/3.0/80x15.png" /><br>
        Copyright &#169; 2012 The <a href="http://usejsdoc.org/contribute-contributors.html">contributors</a> to the JSDoc 3 user guides project<br>
        This site is <a href="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
    </footer>

    <script>prettyPrint();</script>
</body>
</html>