Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

This project is a simple wrapper around the JsDoc Toolkit documentation program

branch: master
README.md

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

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

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 raise an issue

Something went wrong with that request. Please try again.