Generating JavaScript Documentation for Script Objects

One of the things many developers often fail to do is to document their code. Code and documentation comments are not only useful to yourself but also to other developers who may have to contribute to your work or use your work as part of their work. They help increase maintainability, code readability and ease of use. As previously posted, you can create script objects in Adobe LiveCycle Designer to extend standard JavaScript classes with prototype functions and properties. Your script objects can then be distributed among teams for reuse. However, if your script objects contain a large number of functions and properties, your end users may request for documentation.

I have created a Java library that generates Javadoc-styled JavaScript documentation from script objects available in an XDP form. As always, the library can be invoked three ways – command-line, ANT and API call. It is simply a wrapper around the jsdoc-toolkit application. Therefore my util requires jsdoc-toolkit (at least version 2), which can be downloaded from http://code.google.com/p/jsdoc-toolkit/.

The util requires the following four parameters in the exact order:

  1. Path the root of the jsdoc-toolkit folder (e.g. /Users/lerlop/resources/Java/jsdoc-toolkit/2.0.2)
  2. Path the jsdoc template folder you’d like to use (e.g. /Users/lerlop/resources/Java/jsdoc-toolkit/2.0.2/templates/jsdoc)
  3. Path to the XDP file
  4. Path to the output directory

Using ANT


<?xml version="1.0" encoding="UTF-8"?>
<project name="test-ant" basedir=".">

<taskdef
name="xdp-jsdoc-gen"
classname="ac.xfa.jsdoc.ant.Task"
classpath="dist/xdp-jsdoc-gen.jar"/>

<target name="GenerateJSDoc">
<xdp-jsdoc-gen
jsdocToolkitPath="/Users/lerlop/resources/Java/jsdoc-toolkit/2.0.2"
templatePath="/Users/lerlop/resources/Java/jsdoc-toolkit/2.0.2/templates/jsdoc"
xdpPath="test.xdp"
outputPath="/Users/lerlop/Desktop/output"
/>
</target>
</project>

Using command-line


java -jar xdp-jsdoc-gen.jar /Users/lerlop/resources/Java/jsdoc-toolkit/2.0.2 /Users/lerlop/resources/Java/jsdoc-toolkit/2.0.2/templates/jsdoc ../test.xdp /Users/lerlop/Desktop/output

Resulting output


----- Being processing -----
Finished writing /Users/lerlop/Desktop/output/SO.js
Finished writing /Users/lerlop/Desktop/output/ArraySO.js
Finished writing /Users/lerlop/Desktop/output/StringSO.js
Generating jsdoc at /Users/lerlop/Desktop/output/jsdocs
JSDocs created successfully in /Users/lerlop/Desktop/output/jsdocs
----- End -----

Using API


// Instantiate a generator object
JSDocGenerator generator = new JSDocGenerator(jsdocToolkitPath,templatePath, xdpPath, outputPath);

// run
generator.run();

The result

The generated files should look similar to this.

Generated files

And the documentation itself should look similar to this.

JavaScript documentation

As a note, the input form design needs to be in an XDP format. So if your form is in PDF, you need to save it as XDP in LiveCycle Designer or programmatically call LiveCycle Forms to convert PDF to XDP. Moreover, if you have a lot of forms in a LiveCycle repository (e.g. database or Documentum), you can write a Java application that loops through the forms in the repository using the LiveCycle repository API.

Downloads