JsDoc Toolkit Ant Task

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.

About JsDoc Toolkit

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.

Description

This custom 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.

Parameters

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
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

Examples

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>.

Troubleshooting

The ant task has been tested with Rhino 1.6r7

Support

If you find any bugs, etc, or have any ideas for improvements, please get in touch.