-
Notifications
You must be signed in to change notification settings - Fork 105
/
Copy pathabout-getting-started.html
113 lines (110 loc) · 4.87 KB
/
about-getting-started.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
<!DOCTYPE html>
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="description" content="A quick-start to documenting JavaScript with JSDoc.">
<title>Use JSDoc: Getting Started with JSDoc 3</title>
<link rel="stylesheet" href="styles/usejsdoc.css">
<link rel="stylesheet" href="styles/prettify.css">
<link rel="stylesheet" href="styles/css3-github-ribbon.css">
<script src="scripts/prettify.js"></script>
</head>
<body>
<header>
<a href="./index.html">@use JSDoc</a>
</header>
<article>
<h1>Getting Started with JSDoc 3</h1>
<h2>Table of Contents</h2>
<ul>
<li>
<a href="#getting-started">Getting started</a>
</li>
<li>
<a href="#adding-documentation-comments-to-your-code">Adding documentation comments to your code</a>
</li>
<li>
<a href="#generating-a-website">Generating a website</a>
</li>
</ul>
<h2 id="getting-started">Getting started</h2>
<p>JSDoc 3 is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor. You
add documentation comments directly to your source code, right alongside the code itself. The JSDoc
tool will scan your source code and generate an HTML documentation website for you.</p>
<h2 id="adding-documentation-comments-to-your-code">Adding documentation comments to your code</h2>
<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 modules, namespaces, classes, methods, method parameters, and
so on.</p>
<p>JSDoc comments should generally be placed immediately before the code being documented. Each comment
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>
<figure>
<figcaption>The simplest documentation is just a description</figcaption>
<pre class="prettyprint lang-js"><code>/** This is a description of the foo function. */
function foo() {
}
</code></pre>
</figure>
<p>Adding a description is simple—just type the description you want in the documentation comment.</p>
<p>Special "JSDoc tags" can be used to give more information. For example, if the function is a
constructor for a class, you can indicate this by adding a <code>@constructor</code> tag.</p>
<figure>
<figcaption>Use a JSDoc tag to describe your code</figcaption>
<pre class="prettyprint lang-js"><code>/**
* Represents a book.
* @constructor
*/
function Book(title, author) {
}
</code></pre>
</figure>
<p>More tags can be used to add more information. See the <a href="index.html#block-tags">home page</a> for a complete list
of tags that are recognized by JSDoc 3.</p>
<figure>
<figcaption>Adding more information with tags</figcaption>
<pre class="prettyprint lang-js"><code>/**
* Represents a book.
* @constructor
* @param {string} title - The title of the book.
* @param {string} author - The author of the book.
*/
function Book(title, author) {
}
</code></pre>
</figure>
<h2 id="generating-a-website">Generating a website</h2>
<p>Once your code is commented, you can use the JSDoc 3 tool to generate an HTML website from your
source files.</p>
<p>By default, JSDoc uses the built-in "default" template to turn the documentation 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>
<figure>
<figcaption>Running the documentation generator on the command line</figcaption>
<pre class="prettyprint"><code>jsdoc book.js
</code></pre>
</figure>
<p>This command will create a directory named <code>out/</code> in the current working directory. Within that
directory, you will find the generated HTML pages.</p>
</article>
<footer>
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" /></a>
<br>
Copyright © 2011-2019 the
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the
JSDoc 3 documentation project.
<br>
This website is <a href="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and is
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>
<p>
<a href="https://github.com/jsdoc3/jsdoc" class="github-ribbon">Fork me on GitHub</a>
</p>
<script type="text/javascript">
prettyPrint();
</script>
</body>
</html>