about-getting-started.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    
    <meta name="description" content="A quick-start guide to automatically generating JavaScript documentation with JSDoc 3.">
    
    
    <title>Use JSDoc: Getting Started with JSDoc 3</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>Getting Started with JSDoc 3</h1>
    

<div class="about-overview" id="getting-started-overview">
<h3>
    Getting Started
</h3>

<p>
    JSDoc 3 is an API documentation generator for JavaScript, similar to JavaDoc or PHPDoc. You add documentation comments directly to your source code, right along side the code itself. The JSDoc Tool will scan your source code, and generate a complete HTML documentation website for you.
</p>

<h3>
    Adding Documentation Comments to Your Code
</h3>

<p>
    JSDoc's purpose is to document the API of your JavaScript application or library. It is assumed that you will want to document things like: namespaces, classes, methods, method parameters, etc.
</p>

<p>
    JSDoc comments should generally be placed immediately before the code being documented. It must start with a <code>/**</code> sequence in order to be recognized by the JSDoc parser. Comments beginning with <code>/*</code>, <code>/***</code>, or more than 3 stars will be ignored. This is a feature to allow you to suppress parsing of comment blocks.
</p>

<p>
    <b>The simplest documentation is just a description.</b>
</p>

<dl class="example">
<dt></dt>
<dd>
<pre class="prettyprint linenums">
/** This is a description of the foo function. */
function foo() {
}

</pre>
</dd>
</dl>
<p>
    Adding a description is simple, just type the description you want in the documentaton comment.
</p>

<p>
    Special "documentation tags" can be used to give more information. For example, if the function is a constructor, you can indicate this by adding a tag.
</p>

<p>
    <b>Use a documentation tag to describe your code.</b>
</p>

<dl class="example">
<dt></dt>
<dd>
<pre class="prettyprint linenums">
/**
    Represents a book.
    @constructor
 */
function Book(title, author) {
}

</pre>
</dd>
</dl>
<p>
    More tags can be used to add more information. See the Tag Dictionary for a complete list of tags that are recognized by JSDoc 3.
</p>

<p>
    <b>Adding more information with tags.</b>
</p>

<dl class="example">
<dt></dt>
<dd>
<pre class="prettyprint linenums">
/**
    Represents a book.
    @constructor
    @param {string} title - The title of the book.
    @param {string} author - The author of the book.
 */
function Book(title, author) {
}

</pre>
</dd>
</dl>
<h3>
    Generating A Website
</h3>

<p>
    Once your code is commented, you can use the JSDoc 3 Tool to generate an HTML website from the source.
</p>

<p>
    By default, JSDoc will use the "default" template to turn the documentation data into HTML. You can edit this template to suit your own needs, or create an entirely new template if that is what you prefer.
</p>

<p>
    <b>Running the documentation generator on the command line.</b>
</p>

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

</pre>
</dd>
</dl>
<p>
    This command will create a folder named "out" in the current working directory. Within that you will find the generated HTML pages.
</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>