These examples show two versions of a Java application called "SuperProduct", shipped by theacme.com
company. The source code for each version is in the directoriesSuperProduct1.0
andSuperProduct2.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 includedrunme.bat
batch file,runme csh
script, andbuild.xml
ANT build file show each of these steps in turn.
The five steps are as follows:
- Generate Javadoc files for version 1.0.
- Generate Javadoc files for version 2.0.
- 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.
- 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.
- 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. Theand -javadocold
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. -javadocnew
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 thechanges.html
file, thestylesheet-jdiff.css
file, thebackground.gif
file and thechanges
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