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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
|
<html>
<head>
<title>JSDoc Homepage - JavaScript Documentation Tool</title>
<link rel="stylesheet" type="text/css" href="stylesheet.css"/>
<style>
.comment {
color: #000066;
}
.comment_emph {
color: #FF0000
}
</style>
</head>
<body>
<a name="top">
<h1
class="TableHeadingColor"
style="padding: 8px; border: solid black 1px">JSDoc <i class="subh1">- JavaScript Documentation Tool</i></h1></a>
<table>
<tr>
<td>
<ul>
<li><a href="#intro">Introduction</a></li>
<li><a href="#install">Installation</a></li>
<li><a href="#usage">Usage</a></li>
<li><a href="#tagref">Tag Reference</a></li>
<li><a href="#faq">Frequently Asked Questions</a></li>
<li><a href="#moreinfo">More Information</a></li>
</ul>
</td>
</tr>
</table>
<table>
<tr>
<td class="TableSubHeadingColor"><h3><a name="intro">Introduction</a></h3></td>
</tr>
<tr>
<td class="TableRowColor">
<p>
<a href="http://sourceforge.net/projects/jsdoc">JSDoc</a> is a tool that parses inline documentation in JavaScript source files, and produces an documentation of the JavaScript code. This is typically in the form of HTML (<a href="example/index.html">example</a>), but XML and XMI (UML) export are also supported. JSDoc is based on the (very successful) <code>javadoc</code> tool that was created for the same purpose for the Java programming language.
</p>
<p>
JSDoc is primarily intended for libraries of object-oriented JavaScript files, although it also works with procedural code. There is a basic ability to determine inheritance built into the parser, although some more obscure dynamic constructs will not be understood (for example, defining a method to set one class as the superclass of another).
</p>
<p>
Anyone familiar with the <code>javadoc</code> tool will be able to use JSDoc right away; for anyone else it is a very simple matter to get started. JSDoc picks up on comments that are opened with a slash followed by two stars (<code>/**</code>), and closed with the typical star-slash (<code>*/</code>).
</p>
<div class="toplink"><a href="#top">Top</a></div>
</td>
</tr>
</table>
<table>
<tr>
<td class="TableSubHeadingColor"><h3><a name="install">Installation</a></h3></td>
</tr>
<tr>
<td class="TableRowColor">
JSDoc is implemented in Perl, as as such, requires the perl executable. This shouldn't be a problem for Linux/Unix users, but Windows users will probably have to install a perl runtime; <a href="http://www.activeperl.com">ActivePerl</a> is recommended.
<p>JSDoc is distributed as a gzipped tarball, and can be downloaded from the <a href="http://sourceforge.net/projects/jsdoc">JSDoc project page</a>. Once you have downloaded JSDoc-x-x.tgz, just unpack it (tar zxf JSDoc-x-x.tgz on Linux/Unix, use WinZip on Windows), and you're ready to go. You can immediately try out JSDoc on the included test.js JavaScript file by going into the JSDoc directory and entering the command
<pre>
perl jsdoc.pl test.js
</pre>
This should output a set of HTML files in a directory called js_docs_out.
<p>
If you get an error message right away that looks something like
<pre>
Can't locate HTML/Template.pm in @INC ......
</pre>
then you will need to install the HTML::Template Perl module. Luckily, this is a very trivial operation thanks to the <a href="http://www.cpan.org">CPAN</a>. In a Linux/Unix/POSIX-style operating system, open a terminal and run the following command as root:
<pre>
# perl -MCPAN -e 'install HTML::Template'
</pre>
<p>
If you're running Windows and ActivePerl, open a command prompt window and enter the following command:
<pre>
C:\> ppm
</pre>
This will start the Perl Package Manager; at the PPM prompt, enter the following two commands (PPM> is the PPM prompt):
<pre>
PPM> install HTML-Template
PPM> quit
</pre>
<p>
JSDoc <i>should</i> run without problems now.
<div class="toplink"><a href="#top">Top</a></div>
</td>
</tr>
</table>
<table>
<tr>
<td class="TableSubHeadingColor"><h3><a name="usage">Usage</a></h3></td>
</tr>
<tr>
<td class="TableRowColor">
<p>
The general idea of JSDoc is to pick up the form and documentation of code. A major part of JSDoc's functionality is based around documentation strings embedded in JavaScript code. The definitive reference to writing documentation strings for Java (with a large amount of carry-over to JSDoc) can be found at the <a href="http://java.sun.com/j2se/javadoc/writingdoccomments/">javadoc reference page</a>.
<p/>
<p>
JSDoc currently supports a subset of javadoc's '@'-prefixed attributes, but the parser is customizable (as explained later). An example JavaScript file (test.js) is included with the JSDoc distribution. Most functionality of JSDoc can be seen within this script file, however for the impatient a small (and incomplete) example of a common usage of JSDoc is shown below
</p>
<p>
<pre>
<span class="comment">
/**
* Shape is an abstract base class. It is defined simply
* to have something to inherit from for geometric
* subclasses
* @constructor
*/</span>
function Shape(color){
this.color = color;
}
// Bind the Shape_getColor method to the Shape class
Shape.prototype.getColor = Shape_getColor;
<span class="comment">
/**
* Get the name of the color for this shape
* @returns A color string for this shape
*/</span>
function Shape_getColor(){
return this.color;
}
<span class="comment">
/**
* Circle is a subclass of Shape
*/</span>
function Circle(radius){
this.radius = radius;
}
<span class="comment">
/**
* A very rough value for pi
*/</span>
Circle.PI = 3.14;
<span class="comment">
/**
* Get the radius of this circle
* @returns The radius of this circle
*/</span>
function Circle_getRadius(){
return this.radius;
}
// Circle is a subclass of Shape
Circle.prototype = new Shape(null);
</pre>
</p>
<p>
One important difference between javadoc and JSDoc is that JSDoc deals with a much more dynamic language that javadoc. For example, in JavaScript there are many different ways to make one class a subclass of another. The JSDoc parser is able to catch some of these methods, but for particularly dynamic scripts the parser will not be able to do it all on its own. For that reason, JSDoc is customizable with a file called .jsdoc_config that resides in the JSDoc install directory. In this configuration file, JSDoc's behaviour can be customized for any kind of '@'-prefixed attribute. Although this configuration file actually contains Perl code, simple customizations can be done by someone with minimal experience with Perl.
</p>
<!--p>
The '@' attributes that are currently recognized by JSDoc are the following (behaviour is generally the same as javadoc):
<ul>
<li><code>@param</code></li>
<li><code>@argument</code> <i>(synonym for @param)</i></li>
<li><code>@return</code></li>
<li><code>@returns</code> <i>(synonym for @return)</i></li>
<li><code>@author</code></li>
<li><code>@deprecated</code></li>
<li><code>@see</code></li>
<li><code>@version</code></li>
<li><code>@requires</code></li>
<li><code>@throws</code></li>
<li><code>@exception</code> <i>(synonym for @throws)</i></li>
<li><code>@link</code></li>
</ul-->
JSDoc also uses a several non-javadoc '@'-attributes: <code>@constructor</code> and <code>@private</code> are two of the most important ones. As noted above, JavaScript has the capability to be a much more dynamic language than Java. The JSDoc parser can usually find class constructors on it's own, but there are some situations when it needs some additional assistance. For this reason, it is a good practice to always include the <code>@constructor</code> tag in the documentation for a class constructor, as shown below:
<pre>
<span class="comment">
/**
* Nothing is a class that represents nothing
* <span class="comment_emph">@constructor</span>
*/</span>
function Nothing(){
// ... initialization ...
}
</pre>
The <code>@private</code> attribute simply displays the marked method as being private.
</p>
<p>
To get more information on the use of the jsdoc.pl executable itself, run it with the <code>--help</code> commandline option.
</p>
<div class="toplink"><a href="#top">Top</a></div>
</td>
</tr>
</table>
<table>
<tr>
<td class="TableSubHeadingColor"><h3><a name="tagref">Tag Reference</a></h3></td>
</tr>
<tr>
<td class="TableRowColor">
The following is a summary of the supported tags ('@'-attributes) that are supported by JSDoc. For actual examples of the usage of these tags, please see the test.js JavaScript file that is included in the JSDoc distribution.
<table class="tagtable">
<tr>
<td><code>@param</code></td>
<td>
Provide information about a function parameter. A datatype indicator can be added between curly braces with this tag, as follows:
<pre>
/**
* @param {String} paramName This is a string parameter
*/
</pre>
</td>
</tr>
<tr>
<td><code>@argument</code></td>
<td>Synonym for <code>@param</code>
</td>
</tr>
<tr>
<td><code>@return</code></td>
<td>Provide information about the return value of a function.
</td>
</tr>
<tr>
<td><code>@returns</code></td>
<td>Synonym for <code>@return</code>
</td>
</tr>
<tr>
<td><code>@author</code></td>
<td>Provide information about the author of a JavaScript file or a function.
</td>
</tr>
<tr>
<td><code>@deprecated</code></td>
<td>
Signify that a function or class is deprecated, and should not be used if possible.
</td>
</tr>
<tr>
<td><code>@see</code></td>
<td>
Link to another class or function that is of importance to the current class or function. This tag can take several forms.
<p>
To link to another method within the same class:
<pre>
@see #methodName
</pre>
<p>
To link to another class:
<pre>
@see ClassName
</pre>
<p>
To link to a specific method of another class:
<pre>
@see ClassName#methodName
</pre>
</td>
</tr>
<tr>
<td><code>@version</code></td>
<td>Show the version number of the current file or class
</td>
</tr>
<tr>
<td><code>@requires</code></td>
<td>Define a dependency upon another class. The syntax for this tag is as follows:
<pre>
@requires OtherClassName This is text to be shown
</pre>
</td>
</tr>
<tr>
<td><code>@throws</code></td>
<td>
Show that a method can throw a certain type of exception. The syntax for this tag is:
<pre>
@throws ExceptionType This is the label text
</pre>
</td>
</tr>
<tr>
<td><code>@exception</code></td>
<td>Synonym for <code>@throws</code>
</td>
</tr>
<tr>
<td><code>@link</code></td>
<td>This is a powerful tag that can be used to link to a large number of other pages. It is also the only tag that can be used in the description text of a documentation string before the '@'-tag section. The usage is very similar to that of the <code>@see</code> tag, but the entire tag is wrapped in curly braces. For example:
<pre>
/**
* This utility method is also a member of the {@link String} class,
* in the form of the {@link String#utility} method.
*/
</pre>
</td>
</tr>
<tr>
<td><code>@fileoverview</code></td>
<td>This is a special-use tag. If the first block of documentation in a file starts with a <code>@fileoverview</code> tag, the rest of the documentation block will be used to provide a file overview in the documentation.
</td>
</tr>
<tr>
<td><code>@class</code></td>
<td>This tag is used in a constructor's documentation block to provide information about the actual class. The included documentation will then not be included in the constructor's documentation.
</td>
</tr>
<tr>
<td><code>@constructor</code></td>
<td>Signify that a function is the constructor for a class.
</td>
</tr>
<tr>
<td><code>@type</code></td>
<td>Show the return type of a function. For example:
<pre>
/**
* This function returns a String.
* @return The name of the current user
* @type String
*/
</pre>
</td>
</tr>
<tr>
<td><code>@extends</code></td>
<td>Used to show that a class is a subclass of another class. JSDoc is often quite good at picking this up on its own, but in some situations this tag is required.
</td>
</tr>
<tr>
<td><code>@private</code></td>
<td>
Signify that a function or class is private. Private classes and functions will not be available in the documentation unless JSDoc is run with the <code>--private</code> commandline option.
</td>
</tr>
<tr>
<td><code>@final</code></td>
<td>
Flag a value as being a final (constant) value.
</td>
</tr>
<tr>
<td><code>@member</code></td>
<td>
Show that a function is a member of a given class:
<pre>
/**
* @member MyClass
*/
function SomeFunc(){
}
</pre>
</td>
</tr>
<tr>
<td><code>@ignore</code></td>
<td>
Tell JSDoc to totally ignore this method.
</td>
</tr>
<tr>
<td><code>@base</code></td>
<td>
Force JSDoc to view the current class constructor
as a subclass of the class given as the value to
this tag:
<pre>
/**
* This is a subclass of Shape
* @constructor
* @base Shape
*/
function Circle(){
// ...
}
</pre>
</td>
</tr>
<tr>
<td><code>@addon</code></td>
<td>
Mark a function as being an "addon" to a core
JavaScript function that isn't defined within
your own sources, as shown below:
<pre>
/**
* This is an addon function to SomeCoreClass which is
* not defined within our own sources.
* @addon
*/
SomeCoreClass.someFunction = function(){
// ...
} </pre>
</td>
</tr>
<tr>
<td><code>@exec</code></td>
<td><b><i>Experimental!</i></b><br/>
Force JSDoc to "execute" this method as part of its
preprocessing step, in the same way that class
contructors are executed. This can allow attributes
to be added to a class from within a function.
</td>
</tr>
</table>
<div class="toplink"><a href="#top">Top</a></div>
</td>
</tr>
</table>
<table>
<tr>
<td class="TableSubHeadingColor"><h3><a name="faq">Frequently Asked Questions</a></h3></td>
</tr>
<tr>
<td class="TableRowColor">
<ul>
<li><b>I get an error message that says <i>Can't locate HTML/Template.pm in @INC ......</i>. What's going on?</b>
<p>This means that you don't have the HTML::Template perl module installed. Luckily, it's very easy to remedy this problem; see the Installation section of this page.</li>
<li><b>I've found a bug in JSDoc. What should I do?</b>
<p>Go to the <a href="http://sourceforge.net/projects/jsdoc">JSDoc Project Page</a> and register a bug report. You can also send information about the bug to the <a href="http://sourceforge.net/mail/?group_id=30801">JSDoc-user mailing list</a>. But just before you do that, please make sure that it's actually a bug that we're talking about, and not just JSDoc acting differently that what you were expecting.</li>
<li><b>JSDoc segfaults! What should I do?</b>
<p>This is a tough one to answer. JSDoc uses a lot of recursive regular expressions, and sometimes a certain combination of a certain build of perl and a certain JavaScript file will cause perl to segfault while running JSDoc. This problem mostly occurs with binary installations of perl; downloading the most recent source distribution of perl and building it on your own machine seems to solve this problem. </p>
<p>Another action that can sometimes help in this situation (and doesn't require a new install of perl) is by changing the recursion limit for recursive regexes. You can do this by altering the value given to the constant <code>RECURSION</code> in JSDoc.pm (at line 124 at the time of writing). Changing the value from 10 to a lower value, such as 6, can sometimes take care of this issue. The main risk in taking this action is that some deeply-nested constructs in your JavaScript code might not be processed by JSDoc.</p></li>
<li><b>I want JSDoc to do <i>X</i>, but it doesn't!</b>
<p>Well, that's actually not a question, it's more of a statement. However, it is stated quite frequently, so it's not totally out of place here. If you're interested in having a new feature added to JSDoc, you can register a Feature Request at the <a href="http://sourceforge.net/projects/jsdoc">JSDoc Project Page</a>. You may also want to consider sending information about your request to the <a href="http://sourceforge.net/mail/?group_id=30801">JSDoc-user mailing list</a>.</li>
<li><b>Is there a mailing list for JSDoc?</b>
<p>Okay, I admit that this isn't actually a Frequently Asked Question; it's actually just an attempt to promote the <a href="http://sourceforge.net/mail/?group_id=30801">JSDoc-user mailing list</a>.</li>
<li><b>I want to help out with JSDoc. Where should I start?</b>
<p>First of all, help is very welcome! The most welcome kinds of help are context diffs that fix a bug in JSDoc, but pretty much anything that's an attempt at helping out is appreciated. Use the <a href="http://sourceforge.net/mail/?group_id=30801">JSDoc-user mailing list</a>.</li>
</ul>
<div class="toplink"><a href="#top">Top</a></div>
</td>
</tr>
</table>
<table>
<tr>
<td class="TableSubHeadingColor"><h3><a name="moreinfo">More Information</a></h3></td>
</tr>
<tr>
<td class="TableRowColor">
<p>
A very complete and informative article (written by Rainer Eschen) on the use of JSDoc can be found at <a href="http://www.webetiser.de/jsdoc">Webetiser</a>. The article is based on JSDoc 1.5, but is still very relevant. I've been told that the article will be updated in the near future.
<p>
As noted above, the definitive reference for writing Java docstrings can be found at the <a href="http://java.sun.com/j2se/javadoc/writingdoccomments/">javadoc reference page</a>. Please send comments, bugs, complaints, requests for additional information, and whatever else to the <a href="http://sourceforge.net/mail/?group_id=30801">JSDoc mailing list</a>.
</p>
<div class="toplink"><a href="#top">Top</a></div>
</td>
</tr>
</table>
<a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=30801&type=7" width="210" height="62" border="0" alt="SourceForge.net Logo" /></a>
</body>
</html>
|
