This project is a simple wrapper around the JsDoc Toolkit documentation program. It gives the user all the command line options, with the flexibility of using it within an Ant build file.
From the JsDoc Toolkit project page...
JsDoc Toolkit is an application, written in JavaScript, for automatically generating template-formatted, multi-page HTML (or XML, JSON, or any other text-based) documentation from commented JavaScript source code.
Based on the JSDoc.pm project, this was renamed "Jsdoc Toolkit" during development as it grew into more than a simple version upgrade.
Unlike, say, JavaDoc, creating a tool to understand documented JavaScript has long been a diffcult problem, due to JavaScript's relatively loose programming style. The JsDoc Toolkit is another in a long line of tools to attempt to make documenting JavaScript intuituve and easy.
Unlike most other documentation tools, the JsDoc Toolkit program is written in JavaScript, running through the standalone Rhino engine.
This customJs task makes it easier to create the JsDoc Toolkit documentation from the JavaScript, as it can be called from an Ant build file. All the command line parameters for JsDoc Toolkit are still present.
| Attribute | Description | Required |
|---|---|---|
| jsdochome | The home directory of JsDoc Toolkit. Note, must include trailing slash | Yes |
| template | The name of the template to use | Yes |
| outputdir | Where the put the created documents, including trailing slash | Yes |
| inputdir | The directory containing the JavaScript (or other) files | Yes, unless a nested `source` element is supplied |
| outputdir | Where the put the created documents, including trailing slash | Yes |
| encoding | Encoding of the input and output files | No, defaults to `UTF-8` |
| depth | Recursive depth below the inputdir | No, defaults to `10`, though ignored if no `inputdir` attribute is given |
| includeundocumented | Should undocumented functions be included | No, defaults to `false` |
| includeunderscored | Should underscored functions be nicluded | No, defaults to `false` |
| includeprivate | Should private functions be included | No, defaults to `false` |
| verbose | Should the documentation be verbose | No, defaults to `false` |
| extensions | Comma-seperated list of file extensions to include | No, defaults to `js` |
| log | File to ouptut log info to | No |
| config | Points to a JSON-styled file with all the command-line options present, overriding any supplied attributes | No, but if supplied all other parameters are ignored |
First define the jsdoctoolkit task
<taskdef name="jsdoctoolkit" classname="uk.co.darrenhurley.ant.tasks.JsDocToolkit" classpath="/path/to/jsdoctoolkit.jar;/path/to/js.jar"/>
Note that js.jar must also be in the classpath.
Then call the task
<jsdoctoolkit jsdochome="/path/to/jsdoc_toolkit-1.4.0/" template="sunny" outputdir="/output/dir/" inputdir="dir/of/javascript/files/" />
You can also use a nested <fileset> http://ant.apache.org/manual/Types/fileset.html or <filelist> http://ant.apache.org/manual/Types/filelist.html element to load files, or a custom <source> element, which accepts a file attribute
<jsdoctoolkit jsdochome="/path/to/jsdoc_toolkit-1.4.0/" template="sunny" outputdir="/output/dir/">
<source file="/a/js/soucefile.js" />
<source file="/another/js/soucefile.js" />
</jsdoctoolkit>
User-defined arguments can also be passed through (-D parameters on the command line) using a custom <arg> nested element,
<jsdoctoolkit jsdochome="/path/to/jsdoc_toolkit-1.4.0/" template="sunny" outputdir="/output/dir/" inputdir="dir/of/javascript/files/">
<arg name="argOne" value="foo" />
<arg name="argTwo" value="bar" />
</jsdoctoolkit>
There's also an antlib.xml file included, if that's your bag. To use it, make sure the jsdoctoolkit-ant-task-*.jar and rhino's jar is on the classpath, and add xmlns:foo="antlib:uk.co.darrenhurley.ant" to the project element. Then use the task as <foo:jsdoctoolkit>.
- The ant task has been tested with Rhino 1.6r7
If you find any bugs, etc, or have any ideas for improvements, please raise an issue