In my previous post I described how I got started using JsDoc to generate some documentation for the Wiki Text jQuery Plugin.

Running JsDoc on the command line is nice on occasion but in any serious development environment (or my dodgy old laptop) it needs to be incorporated as part of the automated build.

Therefore, I have used Apache Ant and the JsDoc Ant Task to do that very thing.  I’ll get right on with the instructions…

First Steps – Get the Software

OK, if you don’t already have it, the first task is to download and install a copy of Apache Ant (any recent version will do and I’m sure you can follow the excellent installation instructions in the manual).  Do I really need to mention a Java Runtime…?

Next, I downloaded the jsdoc-toolkit-ant-task jar (I have version 1.1.2) and put it into the same Test-JsDoc directory as in the previous post.

And then, following the instructions for the Ant task, I downloaded the Mozilla Rhino JavaScript implementation into the Test-JsDoc directory and unzipped it there – creating a rhino_7Rx subdirectory.

A Quick Note About Rhino Versions

I should just point out that when I did this originally for the Wiki Text plugin, I had Rhino 1.7R2 – and this worked fine.  However, I went and downloaded Rhino 1.7R3 for this article and saw the following error when I ran it:

org.mozilla.javascript.EcmaError: TypeError: org.mozilla.javascript.Undefined@5e1077 is not a function, it is undefined. (JsDoc.js#129)

Switching back to Rhino 1.7R2 solved the problem – so I would recommend using this version unless a newer version of either JsDoc or Rhino has been released which might solve the problem.

On We Go…

Now, with everything in place we need one final file in the directory – a new Ant build script (build.xml).

The image below shows the directory listing with everything needed so that, if you are following this example, you can check you have something similar.

I’ll make this quick and painless and just give you the whole build file before I explain a little about what I’ve done:

<?xml version="1.0" encoding="UTF-8"?>
<project name="Test-JsDoc" default="jsdoc" basedir=".">

	<property name="src.dir" location="${basedir}/script" />

	<property name="jsdoc.dir" location="${basedir}/jsdoc-toolkit" />
	<property name="rhino.dir" location="${basedir}/rhino1_7R2" />
	<property name="ant-task.dir" location="${basedir}" />

	<property name="out.dir" location="${basedir}/target/jsdoc" />

	<!-- Define the classpath for the Apache Ant task - needs Rhino as well. -->
	<path id="jsdoc.classpath">
		<pathelement path="${rhino.dir}/js.jar" />
		<pathelement path="${ant-task.dir}/jsdoc-toolkit-ant-task-1.1.2.jar" />
	</path>

	<!-- Define the Ant Task -->
	<taskdef name="jsdoctoolkit" classname="uk.co.darrenhurley.ant.tasks.JsDocToolkit" classpathref="jsdoc.classpath" />

	<!-- This is the default target - it generates the JsDoc documents -->
	<target name="jsdoc" depends="" description="Generate JsDoc.">
		<jsdoctoolkit jsdochome="${jsdoc.dir}/" template="jsdoc" outputdir="${out.dir}" includeprivate="false">
			<source file="${src.dir}/test.js" />
		</jsdoctoolkit>
	</target>

	<!-- Neat and Tidy, Tidy and Neat - best to clean up afterwards... -->
	<target name="clean" description="Cleanup everything this build script creates.">
		<delete dir="${out.dir}" />
	</target>
</project>

Right, it’s clearly an Ant build file – I’ll assume you are either familiar with Ant or can read the Manual.  Essentially, it’s an XML file so we start with an XML declaration followed by opening the <project…> element.  The name of the project is Test-JsDoc (same as the directory, in this case), the default target to build is the jsdoc target and paths are relative to basedir – which is the Test-JsDoc directory.

Next, I have added a few definitions to parameterise the build – it’s one of those good habits.  First, a few directories, followed by the classpath definition for the jsdoc-toolkit Ant Task.

To use the jsdoc-toolkit Ant Task it needs to be defined in the build script with a <taskdef …>.

And then, at last, we have the main build target which calls the jsdoc-toolkit Ant Task to generate HTML documentation from the specified JavaScript file.  The attributes on the task specify, in order, where the jsdoc-toolkit directory is, the output template name, where to put the generated HTML and, finally, a flag indicating that we don’t want any methods or attributes marked as private in the output.

Before I ended the build script I added a clean target – so I could tidy up before I re-ran the script.

Running The Ant Script

To run the ant script, assuming you have followed all the instructions to install ANT and a Java Runtime Environment, you just need to open a command window in the Test-JsDoc directory and type:

ant

And to remove the generated code (e.g. so you can generate it again once the JavaScript has changed) run:

ant clean

And that’s it, for now.  I hope it helps you – and encourages you to document your JavaScript.  You can always minimise it afterwards if you need – but the documentation will help you and your colleagues get it right first.