You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: about-getting-started.html
+26-24Lines changed: 26 additions & 24 deletions
Original file line number
Diff line number
Diff line change
@@ -25,43 +25,44 @@ <h1>Getting Started with JSDoc 3</h1>
25
25
<h2>Table of Contents</h2>
26
26
<ul>
27
27
<li>
28
-
<ahref="#getting-started">Getting Started</a>
28
+
<ahref="#getting-started">Getting started</a>
29
29
</li>
30
30
<li>
31
-
<ahref="#adding-documentation-comments-to-your-code">Adding Documentation Comments to Your Code</a>
31
+
<ahref="#adding-documentation-comments-to-your-code">Adding documentation comments to your code</a>
32
32
</li>
33
33
<li>
34
-
<ahref="#generating-a-website">Generating A Website</a>
34
+
<ahref="#generating-a-website">Generating a website</a>
35
35
</li>
36
36
</ul>
37
-
<h2id="getting-started">Getting Started</h2>
38
-
<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
39
-
side the code itself. The JSDoc Tool will scan your source code, and generate a complete HTML documentation website for you.</p>
40
-
<h2id="adding-documentation-comments-to-your-code">Adding Documentation Comments to Your Code</h2>
41
-
<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,
42
-
methods, method parameters, etc.</p>
43
-
<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
44
-
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
45
-
parsing of comment blocks.</p>
37
+
<h2id="getting-started">Getting started</h2>
38
+
<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
39
+
alongside the code itself. The JSDoc tool will scan your source code and generate an HTML documentation website for you.</p>
40
+
<h2id="adding-documentation-comments-to-your-code">Adding documentation comments to your code</h2>
41
+
<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,
42
+
classes, methods, method parameters, and so on.</p>
43
+
<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
44
+
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
45
+
you to suppress parsing of comment blocks.</p>
46
46
<figure>
47
-
<figcaption>The simplest documentation is just a description.</figcaption><preclass="prettyprint lang-js"><code>/** This is a description of the foo function. */
47
+
<figcaption>The simplest documentation is just a description</figcaption><preclass="prettyprint lang-js"><code>/** This is a description of the foo function. */
48
48
function foo() {
49
49
}
50
50
</code></pre>
51
51
</figure>
52
-
<p>Adding a description is simple, just type the description you want in the documentaton comment.</p>
53
-
<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
54
-
tag.</p>
52
+
<p>Adding a description is simple—just type the description you want in the documentation comment.</p>
53
+
<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
54
+
a <code>@constructor</code>tag.</p>
55
55
<figure>
56
-
<figcaption>Use a documentation tag to describe your code.</figcaption><preclass="prettyprint lang-js"><code>/**
56
+
<figcaption>Use a JSDoc tag to describe your code</figcaption><preclass="prettyprint lang-js"><code>/**
57
57
* Represents a book.
58
58
* @constructor
59
59
*/
60
60
function Book(title, author) {
61
61
}
62
62
</code></pre>
63
63
</figure>
64
-
<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>
64
+
<p>More tags can be used to add more information. See the <ahref="index.html#block-tags">home page</a> for a complete list of tags that are recognized by JSDoc
65
+
3.</p>
65
66
<figure>
66
67
<figcaption>Adding more information with tags</figcaption><preclass="prettyprint lang-js"><code>/**
<h2id="generating-a-website">Generating A Website</h2>
77
-
<p>Once your code is commented, you can use the JSDoc 3 Tool to generate an HTML website from the source.</p>
78
-
<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
79
-
an entirely new template if that is what you prefer.</p>
77
+
<h2id="generating-a-website">Generating a website</h2>
78
+
<p>Once your code is commented, you can use the JSDoc 3 tool to generate an HTML website from your source files.</p>
79
+
<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
80
+
an entirely new template if that is what you prefer.
81
+
</p>
80
82
<figure>
81
-
<figcaption>Running the documentation generator on the command line.</figcaption><preclass="prettyprint"><code>./jsdoc book.js
83
+
<figcaption>Running the documentation generator on the command line</figcaption><preclass="prettyprint"><code>jsdoc book.js
82
84
</code></pre>
83
85
</figure>
84
-
<p>This command will create a folder named "out" in the current working directory. Within that you will find the generated HTML pages.</p>
86
+
<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>
Copy file name to clipboardExpand all lines: content/en/about-getting-started.md
+31-16Lines changed: 31 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,17 +3,24 @@ title: Getting Started with JSDoc 3
3
3
description: A quick-start to documenting JavaScript with JSDoc.
4
4
---
5
5
6
-
## Getting Started
6
+
## Getting started
7
7
8
-
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.
8
+
JSDoc 3 is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor. You
9
+
add documentation comments directly to your source code, right alongside the code itself. The JSDoc
10
+
tool will scan your source code and generate an HTML documentation website for you.
9
11
10
-
## Adding Documentation Comments to Your Code
12
+
## Adding documentation comments to your code
11
13
12
-
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.
14
+
JSDoc's purpose is to document the API of your JavaScript application or library. It is assumed that
15
+
you will want to document things like modules, namespaces, classes, methods, method parameters, and
16
+
so on.
13
17
14
-
JSDoc comments should generally be placed immediately before the code being documented. It must start with a `/**` sequence in order to be recognized by the JSDoc parser. Comments beginning with `/*`, `/***`, or more than 3 stars will be ignored. This is a feature to allow you to suppress parsing of comment blocks.
18
+
JSDoc comments should generally be placed immediately before the code being documented. Each comment
19
+
must start with a `/**` sequence in order to be recognized by the JSDoc parser. Comments beginning
20
+
with `/*`, `/***`, or more than 3 stars will be ignored. This is a feature to allow you to suppress
21
+
parsing of comment blocks.
15
22
16
-
{% example "The simplest documentation is just a description." %}
23
+
{% example "The simplest documentation is just a description" %}
17
24
18
25
```js
19
26
/** This is a description of the foo function. */
@@ -22,11 +29,12 @@ function foo() {
22
29
```
23
30
{% endexample %}
24
31
25
-
Adding a description is simple, just type the description you want in the documentaton comment.
32
+
Adding a description is simple—just type the description you want in the documentation comment.
26
33
27
-
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.
34
+
Special "JSDoc tags" can be used to give more information. For example, if the function is a
35
+
constructor for a class, you can indicate this by adding a `@constructor` tag.
28
36
29
-
{% example "Use a documentation tag to describe your code." %}
37
+
{% example "Use a JSDoc tag to describe your code" %}
30
38
31
39
```js
32
40
/**
@@ -38,7 +46,8 @@ function Book(title, author) {
38
46
```
39
47
{% endexample %}
40
48
41
-
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.
49
+
More tags can be used to add more information. See the [home page][block-tags] for a complete list
50
+
of tags that are recognized by JSDoc 3.
42
51
43
52
{% example "Adding more information with tags" %}
44
53
@@ -54,17 +63,23 @@ function Book(title, author) {
54
63
```
55
64
{% endexample %}
56
65
57
-
## Generating A Website
66
+
[block-tags]: index.html#block-tags
58
67
59
-
Once your code is commented, you can use the JSDoc 3 Tool to generate an HTML website from the source.
68
+
## Generating a website
60
69
61
-
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.
70
+
Once your code is commented, you can use the JSDoc 3 tool to generate an HTML website from your
71
+
source files.
62
72
63
-
{% example "Running the documentation generator on the command line." %}
73
+
By default, JSDoc uses the built-in "default" template to turn the documentation into HTML. You can
74
+
edit this template to suit your own needs or create an entirely new template if that is what you
75
+
prefer.
76
+
77
+
{% example "Running the documentation generator on the command line" %}
64
78
65
79
```
66
-
./jsdoc book.js
80
+
jsdoc book.js
67
81
```
68
82
{% endexample %}
69
83
70
-
This command will create a folder named "out" in the current working directory. Within that you will find the generated HTML pages.
84
+
This command will create a directory named `out/` in the current working directory. Within that
85
+
directory, you will find the generated HTML pages.
0 commit comments