Newer
Older
Simple JavaScript Duckumentation generator.
,~~.
( 6 )-_,
(\___ )=='-'
\ . ) )
\ `-' / hjw
~'`~'`~'`~'`~
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
JsDuck aims to be a better documentation generator for [ExtJS][].
While it tries to do everything that [ext-doc][] does, it isn't
satisfied with it and aims to make your life much easier.
Basically JsDuck thinks that the following doc-comment really sucks:
/**
* @class Ext.form.TextField
* @extends Ext.form.Field
* <p>Basic text field. Can be used as a direct replacement for traditional
* text inputs, or as the base class for more sophisticated input controls
* (like {@link Ext.form.TextArea} and {@link Ext.form.ComboBox}).</p>
* <p><b><u>Validation</u></b></p>
* <p>The validation procedure is described in the documentation for
* {@link #validateValue}.</p>
* <p><b><u>Alter Validation Behavior</u></b></p>
* <p>Validation behavior for each field can be configured:</p>
* <div class="mdetail-params"><ul>
* <li><code>{@link Ext.form.TextField#invalidText invalidText}</code> :
* the default validation message to show if any validation step above does
* not provide a message when invalid</li>
* <li><code>{@link Ext.form.TextField#maskRe maskRe}</code> :
* filter out keystrokes before any validation occurs</li>
* <li><code>{@link Ext.form.TextField#stripCharsRe stripCharsRe}</code> :
* filter characters after being typed in, but before being validated</li>
* </ul></div>
*/
Ext.form.TextField = Ext.extend(Ext.form.Field, {
Not quite so readable is it? The source of ExtJS is filled with
comments just like that, and when you use ext-doc, you too are forced
to write such comments.
JsDuck does not like it. Although it can handle comments like this,
it would like that you wrote comments like that instead:
/**
* Basic text field. Can be used as a direct replacement for traditional
* text inputs, or as the base class for more sophisticated input controls
* (like {@link Ext.form.TextArea} and {@link Ext.form.ComboBox}).
*
* Validation
* ----------
*
* The validation procedure is described in the documentation for
* {@link #validateValue}.
*
* Alter Validation Behavior
* -------------------------
*
* Validation behavior for each field can be configured:
*
* - `{@link Ext.form.TextField#invalidText invalidText}` :
* the default validation message to show if any validation step above
* does not provide a message when invalid
* - `{@link Ext.form.TextField#maskRe maskRe}` :
* filter out keystrokes before any validation occurs
* - `{@link Ext.form.TextField#stripCharsRe stripCharsRe}` :
* filter characters after being typed in, but before being validated
*/
Ext.form.TextField = Ext.extend(Ext.form.Field, {
As you can see, JsDuck supports formatting comments with friendly
[Markdown][] syntax. And it can infer several things from the code
(like @class and @extends in this case), so you don't have to repeat
yourself.
That's basically it. Have fun.
[ExtJS]: http://www.sencha.com/products/js/
[ext-doc]: http://ext-doc.org/
[Markdown]: http://daringfireball.net/projects/markdown/
Dependencies
------------
To run, you need Ruby 1.8 with [json][] and [RDiscount][] gems.
[json]: http://flori.github.com/json/
[RDiscount]: https://github.com/rtomayko/rdiscount
* [List of supported @tags][tags]
* [List of doc-comment errors(?) found in ExtJS source][errors]
[tags]: https://github.com/nene/jsduck/wiki/List-of-supported-@tags
[errors]: https://github.com/nene/jsduck/wiki/List-of-doc-comment-errors(%3F)-found-in-ExtJS-source
Copying
-------
JsDuck is distributed under the terms of the GNU General Public License version 3.
JsDuck was developed by [Rene Saarsoo](http://triin.net).