JsDuck
======
Simple JavaScript Duckumentation generator.
,~~.
( 6 )-_,
(\___ )=='-'
\ . ) )
\ `-' / hjw
~'`~'`~'`~'`~
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
*
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, {
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.
For development Rake and RSpec are also needed.
[json]: http://flori.github.com/json/
[RDiscount]: https://github.com/rtomayko/rdiscount
More
----
* [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).