JDiff - Running the Examples


These examples show two versions of a Java application called "SuperProduct", shipped by the acme.com company. The source code for each version is in the directories SuperProduct1.0 and SuperProduct2.0. The results of JDiff comparing the two versions can be seen here.
There are five steps to complete the example, two of which are ordinary Javadoc commands, and three involve running JDiff, which is a Javadoc doclet. The included runme.bat batch file, runme csh script, and build.xml ANT build file show each of these steps in turn.
The five steps are as follows:
  1. Generate Javadoc files for version 1.0.
  2. Generate Javadoc files for version 2.0.
  3. Use JDiff to generate an XML description of the API for version 1.0.

    javadoc -J-Xmx128m -doclet jdiff.JDiff -docletpath ..\..\lib\jdiff.jar
      -apiname "SuperProduct 1.0" -sourcepath ..\SuperProduct1.0


    The -apiname argument tells JDiff where to store the XML which represents version 1.0 of the SuperProduct API. The -sourcepath argument tells JDiff where to find the source code for the SuperProduct application.
  4. Use JDiff to generate an XML description of the API for version 2.0.
    This is the same as Step 3, with a different -apiname argument and a different source code location for version 2.0 of SuperProduct.
  5. Compare the two APIs and generate the HTML report of the differences.

    javadoc -J-Xmx128m -doclet jdiff.JDiff -docletpath ..\..\lib\jdiff.jar -d newdocs
      -oldapi "SuperProduct 1.0" -newapi "SuperProduct 2.0"
      -javadocold "../../olddocs/" -javadocnew "../../newdocs/" -sourcepath ..\..\lib Null

    The optional -d argument indicates where the generated HTML files should go. The key arguments are -oldapi and -newapi, which tell JDiff which APIs to compare. The names given to these arguments must match the names given to -apiname in steps 3 and 4. The -javadocold and -javadocnew arguments are the locations of the documentation generated by Javadoc in steps 1 and 2. The Null class is only present because Javadoc needs a class to scan. It is not used by JDiff in this step.

Once these steps are complete, the report of the differences between he two versions of SuperProduct is located at newdocs/changes.html and in the changes subdirectory there.
SHIPPING NOTE: JDiff-generated files comprise the changes.html file, the stylesheet-jdiff.css file, the background.gif file and the changes subdirectory and its HTML files. No other files need to be shipped for the results of JDiff to be used with a product's documentation.
See also the reference page for JDiff for a complete description of each argument and more help.

Copyright © 2001-2003 Matthew B. Doar
JDiff Doclet, v1.0.10