JS doc with ant

Question

I am trying to get ant to run my jsdoc toolkit. After I create my build.xml from the examples at the site, I end up with this:

<taskdef name="jsdoctoolkit" classname="uk.co.darrenhurley.ant.tasks.JsDocToolkit" classpath="/jsdoc/jsrun.jar;/jsdoc/java/classes/js.jar"/>

As I run #ant I get the following error:

/pathto/jsdoc_toolkit-2.3.2/build.xml:1: Unexpected element "{}taskdef" {antlib:org.apache.tools.ant}taskdef

As I am now java developer, I can only guess that my classname ( which I took from the website ) is incorrect. But I have now clue what to replace it with.

can anyone help me with this?

Answer 1

I've not had much luck trying to get the jsdoctoolkit task working either. Luckily it's pretty easy to run JSDoc Toolkit directly from Ant without using the task.

<property name="source.dir" value="source" />
<property name="doc.dir" value="docs" />

<property name="tool.dir" value="tools" />

<property name="jsdoctoolkit.dir" value="${tool.dir}/jsdoc_toolkit-2.4.0/jsdoc-toolkit" />


<target name="docs" description="Generates documentation">
    <sequential>
        <delete dir="${doc.dir}"/>
        <mkdir dir="${doc.dir}" />

        <echo message="Running JSDoc Toolkit"/>

        <!-- The java exe is told to run in the dir where our source files reside.
                 If we instead ran it from the dir that the build file is in and gave it
                 full paths to the source files the documentation would include the full
                 filesystem paths (c:\path\to\source\) instead of relative ones.
                 Since this command is running in the source dir, all of the paths
                 given to it must first traverse down a level (../) to get back to the
                 build file dir.
        -->
        <exec executable="java" dir="${source.dir}">
            <arg line="-jar ../${jsdoctoolkit.dir}/jsrun.jar ../${jsdoctoolkit.dir}/app/run.js" />
            <!-- -d tells JSDoc toolkit where to output the documentation -->
            <arg line="-d=../${doc.dir}" />
            <!-- use the default template -->
            <arg line="-t=../${jsdoctoolkit.dir}/templates/jsdoc" />
            <!-- Create an arg element for each file you want to include in the documentation -->
            <arg line="my-javascript-file.js" />
            <arg line="another-javascript-file.js" />
            <arg line="subdir/yet-another-javascript-file.js" />
        </exec>
    </sequential>
</target>

This target assumes that the project has the following directory structure:

build.xml
docs/
source/
    my-javascript-file.js
    another-javascript-file.js
    subdir/
        yet-another-javascript-file.js
tools/
    jsdoc_toolkit-2.4.0/
        jsdoc-toolkit/
            jsrun.js
            app/
                run.js

Answer 2

Your immediate assumption is likely to be incorrect. The XML error you encountered, is telling you that the parser encountered your <taskdef> element in the wrong location within the XML structure. In fact at this point, it hadn't even got around to looking inside the element itself so your classname attribute can't be the problem.

As Pointy says, try posting the entirety of your XML - or at least, have a look at it yourself and check that the <taskdef> element is positioned correctly. It needs to be at the top level of the <project> tag. If you have it nested within other elements, this is not valid and it won't work.

Typically your buildfile might look something like this:

<project name="MyProject" default="dist" basedir=".">
    <description>
        simple example build file
    </description>
  <!-- set global properties for this build -->
  <property name="src" location="src"/>
  <property name="build" location="build"/>
  <property name="dist"  location="dist"/>

  <taskdef name="jsdoctoolkit" classname="uk.co.darrenhurley.ant.tasks.JsDocToolkit" classpath="/jsdoc/jsrun.jar;/jsdoc/java/classes/js.jar"/>

  <!-- Rest of file... -->

In all cases, if you move your taskdef line from where it is now, to directly below the <project> line at the top of the file, I expect this will fix your issue.