JSDoc3 Ant Task

This is a simple wrapper around the JSDoc3 JavaScript documentation generation tool. It allows users to use JSDoc3 in an ant build file.

Prerequisites

You should have JSDoc3 installed somewhere.

https://github.com/jsdoc3/jsdoc

Installation

Presumably, you've already got the code, but if not, go and get it:
https://github.com/jannon/jsdoc3-ant-task

Build

From the project directory just run ant dist

That will build everything and in build/jar you will find a jsdoc3-ant-task-.jar file. That's the jar you'll use for the classpath in the taskdef in your ant build file (see below)

Usage

Assuming you have the following properties defined:

jsdoc.home - the location of your jsdoc3 installation
jsdoc3-task-jar - the location of the task jar that was build above
rhino-jar - the location of the rhino jar (e.g. ${jsdoc.home}/lib/js.jar or the one found in lib/rhino of this project)

Then you would use the task like so:

<taskdef name="jsdoc" classname="net.jannon.ant.tasks.JsDoc3" classpath="${jsdoc3-task-jar}:${rhino-jar}"/>
<jsdoc jsdochome="${jsdoc.home}" to="${docs.dir}" dir="${src.dir}" />

Attributes

jsdochome - (Required) - The home directory of JSDoc3
dir - (Optional*) - The directory containing source files to document
file - (Optional*) - The source file to document
template - (Optional) - The name of the template to use. Default: default.
to - (Optional) - The directory in which to place the generated documentation. Default: out.
encoding - (Optional) - The encoding of the source files and documentation. Defaults: utf-8.
private - (Optional) - Whether or not to include private members/methods in the documentation. Default: false
recurse - (Optional) - Whether or not to recurse into the subdirectories of the directory identified by the 'dir' attribute. Default: false
tutorials - (Optional) - The location of the tutorials to use
Either 'file' or 'dir' or nested filesets must be specified.

Nested Elements

The jsdoc3 ant task supports a few nested elements

Filesets and Filelists

You can specify the source files using filesets or filelists

Arguments

The jsdoc3 ant task supports all JSDoc3 command line options. For those that aren't exposed by the attributes, (e.g. --explain, --help, etc.), or if JSDoc3 gets adds new ones before this task is updated, you can add nested arg elements and they will be passed through.

Examples

<jsdoc3 jsdochome="${jsdoc.home}" 
    to="${docs.dir}/testone" 
    file="${test.dir}/${test.file}" />

Basic file

<jsdoc3 jsdochome="${jsdoc.home}" 
    to="${docs.dir}/testtwo" 
    dir="${test.dir}/"
    template="spartan" />

Basic directory using the template named "spartan"

<jsdoc3 jsdochome="${jsdoc.home}" 
    to="${docs.dir}/testthree"
    private="true">
    <fileset dir="${test.dir}/" />
</jsdoc3>

Nested fileset, documenting private members

<jsdoc3 jsdochome="${jsdoc.home}" 
    to="${docs.dir}/testfive" 
    dir="${test.dir}">
    <arg line="-X" />
</jsdoc3>

Nested argument

License

See file "LICENSE.md" in this distribution for more details about terms of use.

jannon/jsdoc3-ant-task