You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1033 lines
42 KiB
1033 lines
42 KiB
12 years ago
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
|
||
|
|
<HTML>
|
||
|
|
<HEAD>
|
||
|
|
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
|
||
|
|
<TITLE>JDiff User Documentation</TITLE>
|
||
|
|
</HEAD>
|
||
|
|
<BODY BGCOLOR="#ffffff">
|
||
|
|
<table width="100%">
|
||
|
|
<tr>
|
||
|
|
<td align="left"><A href="http://sourceforge.net/projects/javadiff/">
|
||
|
|
<IMG src="http://javadiff.cvs.sourceforge.net/*checkout*/javadiff/jdiff/lib/jdiff_logo.gif"
|
||
|
|
width="88" height="31" border="0" alt="JDiff Logo"></A></td>
|
||
|
|
<td align="right"><A href="http://sourceforge.net"> <IMG src="http://sourceforge.net/sflogo.php?group_id=37160" width="88" height="31" border="0" alt="SourceForge Logo"></A></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
|
||
|
|
<center>
|
||
|
|
<H1>JDiff User Documentation</H1><br>
|
||
|
|
</center>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
<b>JDiff</b> is a Javadoc <a
|
||
|
|
href="http://java.sun.com/j2se/javadoc">doclet</a> which generates an
|
||
|
|
HTML report of all the packages, classes, constructors, methods, and
|
||
|
|
fields which have been removed, added or changed in any way, including
|
||
|
|
their documentation, when two APIs are compared. This is very useful
|
||
|
|
for describing exactly what has changed between two releases of a
|
||
|
|
product. Only the API (Application Programming Interface) of each
|
||
|
|
version is compared. It does not compare what the source code does
|
||
|
|
when executed.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<HR>
|
||
|
|
<H2>CONTENTS</H2>
|
||
|
|
<UL>
|
||
|
|
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#overview"><B>Overview</B></A></P></LI>
|
||
|
|
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#installation"><B>Installation</B></A></P></LI>
|
||
|
|
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#synopsis"><B>Synopsis</B></A></P></LI>
|
||
|
|
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#output"><B>Output</B></A></P></LI>
|
||
|
|
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#addingcomments"><B>Adding
|
||
|
|
Comments to a Report</B></A></P></LI>
|
||
|
|
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#troubleshooting"><B>Troubleshooting</B></A></P></LI>
|
||
|
|
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#errorswarnings"><B>Errors
|
||
|
|
and Warning Messages</B></A></P></LI>
|
||
|
|
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#differencestatistics"><B>Difference Statistics</B></A></P></LI>
|
||
|
|
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#limitations"><B>Limitations</B></A></P></LI>
|
||
|
|
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#furtherreading"><B>Further Reading</B></A></P></LI>
|
||
|
|
</UL>
|
||
|
|
<HR>
|
||
|
|
|
||
|
|
<A NAME="overview"></A>
|
||
|
|
<H2>OVERVIEW</H2>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
The basic sequence of operations is to run JDiff on one set of source
|
||
|
|
files to create an XML file which represents the API for that version
|
||
|
|
of a product. Then JDiff is run again on another set of source files
|
||
|
|
to create an XML file which represents the API for the next version of
|
||
|
|
a product. Finally, JDiff compares the two APIs as represented in the
|
||
|
|
XML files and generates an HTML report which describes the differences
|
||
|
|
between the two APIs, together with comments describing the reasons
|
||
|
|
for the differences. This whole process can be executed as separate
|
||
|
|
Javadoc steps (either from Ant or the command line) or by simply using
|
||
|
|
the Ant JDiff task provided.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
The results are written into a file called <code>changes.html</code>,
|
||
|
|
with more files in a subdirectory called <code>changes</code>. These
|
||
|
|
files can contain links to existing Javadoc documentation. A CSS
|
||
|
|
stylesheet is also generated in the file
|
||
|
|
<code>stylesheet-jdiff.css</code>, and this uses a background image in
|
||
|
|
<code>background.gif</code>. <i>These are the only files which usually
|
||
|
|
need to be shipped with a product to include a report of what has
|
||
|
|
changed since the previous release</i>. If the <code>-stats</code>
|
||
|
|
option was used, then the file <code>black.gif</code> should also be
|
||
|
|
shipped.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
There is a working example of how to use JDiff in the <code>examples</code>
|
||
|
|
directory of the source distribution.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
|
||
|
|
<A NAME="installation"></A>
|
||
|
|
<H2>INSTALLATION</H2>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
Unpack the jdiff-1.1.1.zip file. This will produce a directory named
|
||
|
|
"jdiff-1.1.1" containing all that is necessary to use JDiff to produce
|
||
|
|
your own reports. See the file "example.xml" in that directory for an
|
||
|
|
example of how to use the Ant JDiff task. The file "jdiff.html"
|
||
|
|
contains more information about using JDiff.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
If you are using the complete source distribution, then you should be
|
||
|
|
able to simply type "ant" at the top-level to produce a working
|
||
|
|
example report.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
The Ant JDiff task needs Ant 1.6.1 to work correctly. Using Ant
|
||
|
|
1.5 will produce the error:
|
||
|
|
<pre>
|
||
|
|
Error: two projects are needed, one <old> and one <new>
|
||
|
|
</pre>
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
No Windows registry entries are changed by JDiff. To remove JDiff,
|
||
|
|
simply delete the directory where it is was unpacked.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
|
||
|
|
<H2><A NAME="synopsis"></A>SYNOPSIS</H2>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
The Ant JDiff task has the following parameters:
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
<table border="1" cellpadding="2" cellspacing="0">
|
||
|
|
<tr>
|
||
|
|
<td><b>Attribute</b></td>
|
||
|
|
<td><b>Description</b></td>
|
||
|
|
<td align="center"><b>Required</b></td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td>destdir</td>
|
||
|
|
<td>The location where the JDiff report will be generated. Defaults to a directory "jdiff_report" in the directory from where Ant was executed.</td>
|
||
|
|
<td align="center">No</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td>stats</td>
|
||
|
|
<td>Generate an HTML page of statistical information about the
|
||
|
|
differences between the two APIs. Defaults to "off".</td>
|
||
|
|
<td align="center">No</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td>docchanges</td>
|
||
|
|
<td>Enables comparison of Javadoc documentation. Defaults to "off".</td>
|
||
|
|
<td align="center">No</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td>verbose</td>
|
||
|
|
<td>Increase the logging vebosity of the task. Defaults to "off".</td>
|
||
|
|
<td align="center">No</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
<b>Parameters specified as nested elements</b>
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
The <code>old</code> and <code>new</code> elements are used to describe the projects to be compared.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
<table border="1" cellpadding="2" cellspacing="0">
|
||
|
|
<tr>
|
||
|
|
<td><b>Attribute</b></td>
|
||
|
|
<td><b>Description</b></td>
|
||
|
|
<td align="center"><b>Required</b></td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td>name</td>
|
||
|
|
<td>The name of the project, e.g. "My Project Version 1". The name, with spaces replaced by underscores, is used as the name of the XML file in <code>destdir</code>,
|
||
|
|
which is generated by JDiff to represent the structure of the source files of this project.</td>
|
||
|
|
<td align="center">Yes</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td>javadoc</td>
|
||
|
|
<td>The location of a Javadoc report for this project. If this attribute is not used, then a Javadoc report for the project will be generated in a subdirectory named <code>name</code> in <code>destdir</code>.</td>
|
||
|
|
<td align="center">No</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
Note: the <code>old</code> and <code>new</code> elements only have <code>DirSet</code> nested elements, not <code>FileSet</code> ones.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
The complete list parameters that can be passed to the JDiff doclet,
|
||
|
|
either through the Ant Javadoc task or directly at the command line,
|
||
|
|
is as follows:
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<PRE STYLE="margin-left: 1cm; margin-right: 1cm; margin-bottom:0.5cm">
|
||
|
|
javadoc -doclet <b>jdiff.JDiff</b> -docletpath jdiff.jar
|
||
|
|
[-apiname <<i>API name</i>>]
|
||
|
|
[-apidir <<i>optional directory where the API XML file is to be placed</i>>]
|
||
|
|
[-oldapi <<i>name of old API</i>>]
|
||
|
|
[-oldapidir <<i>optional directory where the old API XML file is located</i>>]
|
||
|
|
[-newapi <<i>name of new API</i>>]
|
||
|
|
[-newapidir <<i>optional directory where the new API XML file is located</i>>]
|
||
|
|
[-sourcepath <<i>source path</i>>]
|
||
|
|
[-javadocnew <<i>javadoc files location for the new API</i>>]
|
||
|
|
[-javadocold <<i>javadoc files location for the old API</i>>]
|
||
|
|
[-baseURI <<i>base</i>>]
|
||
|
|
[-excludeclass <<i>exclusion level</i>>]
|
||
|
|
[-excludemember <<i>exclusion level</i>>]
|
||
|
|
[-nosuggest <<i>suggestion level</i>>]
|
||
|
|
[-firstsentence]
|
||
|
|
[-docchanges]
|
||
|
|
[-checkcomments]
|
||
|
|
[-packagesonly]
|
||
|
|
[-showallchanges]
|
||
|
|
[-retainnonprinting]
|
||
|
|
[-excludetag <<i>exclude tag</i>>]
|
||
|
|
[-stats]
|
||
|
|
[-windowtitle <<i>text</i>>]
|
||
|
|
[-doctitle <<i>HTML text</i>>]
|
||
|
|
[-version]
|
||
|
|
[-help]
|
||
|
|
</PRE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
NOTE: Either <code>-apiname</code>, or both <code>-oldapi</code> and
|
||
|
|
<code>-newapi</code> must be used. All other arguments are optional.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
The <code>-d directory</code> argument works just as with Javadoc, redirecting
|
||
|
|
the HTML output to the given directory.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<P STYLE="margin-left: 1cm; margin-bottom: 0cm">The arguments for the JDiff doclet are:</P>
|
||
|
|
<DL>
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-apiname</code> <<i>API name</i>></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
Define the name which will be associated
|
||
|
|
with the specified API. If the name which is given here has space
|
||
|
|
characters, they will be
|
||
|
|
replaced by underscore characters. This name with no spaces is used as the name of the XML
|
||
|
|
file. It is also written into the XML file as an attribute of the top
|
||
|
|
element.
|
||
|
|
E.g. "SuperProduct 1.0" generates an XML file named
|
||
|
|
"SuperProduct_1.0.xml".
|
||
|
|
The XML file is always generated in the current directory, unless
|
||
|
|
overridden by the <code>-apidir</code> argument.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-oldapi</code> <<i>name of old API</i>></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
The name of the old or previous version of an
|
||
|
|
API or product, e.g. "SuperProduct 1.0", which is to be one of the
|
||
|
|
APIs compared.
|
||
|
|
This name is the name which was given to <code>-apiname</code> when
|
||
|
|
the XML file was generated.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-newapi</code> <<i>name of old API</i>></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
The name of the new or later version of an
|
||
|
|
API or product, e.g. "SuperProduct 2.0", which is to be one of the
|
||
|
|
APIs compared.
|
||
|
|
This name is the name which was given to <code>-apiname</code> when
|
||
|
|
the XML file was generated.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-apidir</code> <<i>API directory</i>></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
Defines the directory where the API XML file is to be placed. Used in
|
||
|
|
conjunction with the <code>-apiname</code> argument.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-oldapidir</code> <<i>old API directory</i>></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
Defines the directory where the XML file for the old API is located.
|
||
|
|
Used in conjunction with the <code>-oldapi</code> argument. Default is the current
|
||
|
|
directory.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-newapidir</code> <<i>new API directory</i>></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
Defines the directory where the XML file for the new API is located.
|
||
|
|
Used in conjunction with the <code>-newapi</code> argument. Default is the current
|
||
|
|
directory.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-sourcepath</code> <<i>source path</i>></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
Define the path to the set of Java source
|
||
|
|
files (the API)
|
||
|
|
to be scanned, e.g. <code>examples/SuperProduct1.0</code>. The
|
||
|
|
slashes in this argument should match the local architecture.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-javadocnew</code> <<i>javadoc files location for the new API</i>></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
The location of existing Javadoc files
|
||
|
|
for the new API, e.g. "http://java.sun.com/j2se/<b>1.5.0</b>/docs/api/" for the
|
||
|
|
public documentation for J2SE1.5.0. The default value is "../", which implies
|
||
|
|
that the documentation directory generated by Javadoc is at the same level as
|
||
|
|
the "changes.html" file generated by JDiff. Slashes are always
|
||
|
|
forward in the argument, since this is an HTML link. <b>The argument
|
||
|
|
should also always end in a forward slash.</b> If a relative value is
|
||
|
|
given, it should be relative to files in the "changes" directory
|
||
|
|
generated by JDiff.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-javadocold</code> <<i>javadoc files location for the old API</i>></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm"> The location of existing
|
||
|
|
Javadoc files for the old API, e.g. "http://java.sun.com/j2se/<b>1.5.0</b>/docs/API/"
|
||
|
|
for the public documentation for J2SE1.5.0. The default value is null, which
|
||
|
|
results in no links to Javadoc-generated documentation for the previous
|
||
|
|
release. Slashes are always forward in the argument, since this is an HTML
|
||
|
|
link. <b>The argument should also always end in a forward slash.</b> If a relative
|
||
|
|
value is given, it should be relative to files in the "changes" directory
|
||
|
|
generated by JDiff.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<A NAME="baseURIoption"></A>
|
||
|
|
<code>-baseURI</code> <<i>base</i>></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
Use \"base\" as the base location of the various DTDs used by
|
||
|
|
JDiff. For example, <code>-baseURI "file:///C:/jdiff/lib"</code> would cause
|
||
|
|
the XML parser to use the copies which are shipped in the
|
||
|
|
<code>lib</code> directory, if JDiff is installed in
|
||
|
|
<code>C:\jdiff</code>. Note that there are <i>three</i> forward slashes
|
||
|
|
after "file:".
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-excludeclass</code> <<i>exclusion level</i>></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
This can be set to "public",
|
||
|
|
"protected", "package", or "private". If it is set to "protected", only
|
||
|
|
classes which are public or protected will be shown. If it is set to
|
||
|
|
"public", then only public classes are shown. The default is
|
||
|
|
"protected". If this is changed, the Javadoc <code>-private</code>
|
||
|
|
argument must also be passed to Javadoc.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-excludemember</code> <<i>exclusion level</i>></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
This can be set to "public",
|
||
|
|
"protected", "package", or "private". If it is set to "protected", only
|
||
|
|
members (constructors, methods and fields) which are public or protected will be shown. If it is set to
|
||
|
|
"public", then only public members are shown. The default is
|
||
|
|
"protected".
|
||
|
|
If this is changed, the Javadoc <code>-private</code>
|
||
|
|
argument must also be passed to Javadoc.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-firstsentence</code></dt>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
This argument causes JDiff to save only the first sentence of each
|
||
|
|
Javadoc comment as part of
|
||
|
|
the API. This is only necessary when the XML file representing the
|
||
|
|
API is being generated. See <code>-docchanges</code> for how to
|
||
|
|
note documentation changes as differences.<br>
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-docchanges</code></dt>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
This argument enables comparison of Javadoc documentation.
|
||
|
|
By default, changes in the saved Javadoc documentation
|
||
|
|
are not noted as changes (or as removals and related
|
||
|
|
additions). See <code>-firstsentence</code> option for how to compare just
|
||
|
|
the first sentence in Javadoc documentation.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-nosuggest</code> <<i>suggestion level</i>></dt>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
This can be set to "all", "remove", "add",
|
||
|
|
or "change". The effect of setting this to "all" is to stop comments
|
||
|
|
for any changes at all being suggested. Any comments which are to
|
||
|
|
appear in the report must then be written by the user (see <a href="#addingcomments">below</a>).
|
||
|
|
If it is set to "change", then
|
||
|
|
comments will not be suggested for changes, but will be suggested for
|
||
|
|
removals and additions. The default is that comments are suggested for
|
||
|
|
all possible places.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-checkcomments</code></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
If this argument is used, JDiff
|
||
|
|
will warn the user when the report is generated if there are comments
|
||
|
|
which do not end in a period, question mark or exclamation mark.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-packagesonly</code></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
If this argument is used, JDiff
|
||
|
|
will not scan classes specified on the command line. This should
|
||
|
|
only need to be used with the "jdiffjar" script, when
|
||
|
|
comparing Jar files.
|
||
|
|
If this options is not used when comparing Jar files, duplicate
|
||
|
|
classes with no packages ("anonymous" classes) may be
|
||
|
|
wrongly reported by JDiff.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-showallchanges</code></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
If this argument is used, JDiff will show changes in
|
||
|
|
native and synchronized modifiers. See <a href="http://java.sun.com/j2se/1.4.1/docs/tooldocs/solaris/javadoc.html#generatedapideclarations">here</a> for why these are not shown by default.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-retainnonprinting</code></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
Retain non-printable characters
|
||
|
|
in comments. By default, JDiff removes non-printable characters
|
||
|
|
from comments which it uses.
|
||
|
|
This should only really be necessary if the first line of a
|
||
|
|
comment has used explicit Unicode character escape sequences which
|
||
|
|
cannot be printed, or more importantly for JDiff, read in from XML.
|
||
|
|
If this option is used, JDiff may fail to read in an XML
|
||
|
|
file, and exit with an error message about "an invalid XML character (Unicode:
|
||
|
|
0x....)" on a certain line in the file. Turning off this option does
|
||
|
|
make creating large XML files a little faster.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-excludetag <<i>exclude tag</i>></code></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
The argument passed in with this causes
|
||
|
|
JDiff to ignore program elements (packages, classes, constructors,
|
||
|
|
methods, fields) which contain the given exclude tag in their comment blocks,
|
||
|
|
e.g. " @exclude", " @docset Internal". The extra space in front of "@" is
|
||
|
|
to stop Javadoc from expanding the name into a file containing commands on
|
||
|
|
the compile line. White space is trimmed off before the string is used.
|
||
|
|
|
||
|
|
Another solution to passing "@" as part of an argument is to pass @foo,
|
||
|
|
and then create a file named <code>foo</code>, containing
|
||
|
|
<code>-excludetag @exclude</code>.
|
||
|
|
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-stats</code></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
Generate an HTML page of statistical information about the
|
||
|
|
differences between the two APIs.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-windowtitle <<i>text</i>></code></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
Specify the title used in the browser window for the report.
|
||
|
|
By default, this is
|
||
|
|
"API Differences Between <name of old API> and
|
||
|
|
<name of new API>".
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-doctitle <<i>HTML text</i>></code></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
Specify the title used on the first page of the report.
|
||
|
|
By default, this is
|
||
|
|
"API Differences Between <name of old API> and
|
||
|
|
<name of new API>".
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-version</code></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
Display the version of JDiff.
|
||
|
|
</DD>
|
||
|
|
|
||
|
|
<DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
<code>-help</code></DT>
|
||
|
|
<DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
|
||
|
|
Display the usage summary for JDiff.
|
||
|
|
</DD>
|
||
|
|
</DL>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
|
||
|
|
<H2><A NAME="output"></A>OUTPUT</H2>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
<ul>
|
||
|
|
<li>Interfaces appear in <i>italics</i>, just as in Javadoc documentation.</li>
|
||
|
|
<li>When a package or class appears in <b>bold</b>, it has been added in
|
||
|
|
the new version or API.</li>
|
||
|
|
<li>When a package or class appears <strike>struck through</strike>, it has been removed in
|
||
|
|
the new version or API.</li>
|
||
|
|
<li>When a constructor is added, two entries are added to the "All
|
||
|
|
Differences" index: one for the addition of a new constructor, and
|
||
|
|
one for the change of the class. The constructor entry has
|
||
|
|
"constructor" after it.</li>
|
||
|
|
<li>There are some complex changes which can occur between versions, for example, when two or more methods with the same name change simultaneously, or when a method or field is moved into or from a superclass.
|
||
|
|
In these cases, the change will be seen as a removal and an addition, rather than as a change. Unexpected removals or additions are often part of one of these type of changes.</li>
|
||
|
|
<li>With large packages, it is often necessary to change the memory parameters for
|
||
|
|
Javadoc, e.g. pass in <code>-J-Xmx128m</code> to Javadoc.</li>
|
||
|
|
<li>The <code>api.xsd</code> template describes the format of the XML
|
||
|
|
for the APIs, and the <code>comments.xsd</code> template describes the format
|
||
|
|
of the XML for the comments. The API template is independent of any
|
||
|
|
related work at Sun, but the intention is to adopt whatever becomes
|
||
|
|
the <i>de facto</i> standard in the future, whilst retaining backward
|
||
|
|
compatibility. To enable validation, set the boolean <code>validateXML</code> in
|
||
|
|
the file <code>XMLToAPI.java</code> and recompile.</li>
|
||
|
|
<li>Comments in the comments XML file do get reordered during
|
||
|
|
regeneration. This is harmless.</li>
|
||
|
|
</ul>
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
|
||
|
|
<H2><A NAME="addingcomments"></A>ADDING COMMENTS TO A REPORT</H2>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
Comments can be added to a report by using a text editor to add text
|
||
|
|
to the "user_comments_X_to_Y.xml" file, where "X" and "Y" are the
|
||
|
|
names of the two APIs being compared. This file is automatically regenerated
|
||
|
|
each time the report is generated.
|
||
|
|
If the <code>-d directory</code> argument is used, the user comments XML
|
||
|
|
file also appears, and is expected, in the named directory.
|
||
|
|
|
||
|
|
<p>Comments which become unused are
|
||
|
|
moved to the end of the file and placed inside XML comments.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE> The text which is added can be HTML text if necessary, but if the
|
||
|
|
HTML is incorrect, JDiff may fail to read the comments file and exit. Note that
|
||
|
|
the required HTML is in fact <a href="http://www.w3.org/TR/xhtml1/diffs.html">XHTML</a>. Since this HTML is stored in an XML document, single tags without their closing ("slash") element are not permitted.
|
||
|
|
For example, most browsers permit HTML which looks like "<p>Here is some
|
||
|
|
text.", with no closing tag. XML requires that either a closing tag exists ("</p>"),
|
||
|
|
or that the single tag is closed, e.g. "<p/>Here is some text.".
|
||
|
|
HTML p, br and hr tags can be single, due to common usage.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
To write comments for a particular removal, addition or change in the
|
||
|
|
JDiff-generated report, edit the comments XML file. Your changes will
|
||
|
|
be automatically incorporated into a new version of this file when the
|
||
|
|
report is next generated. Search the file for the identifier for the
|
||
|
|
particular removal, addition or change, using the package name, class
|
||
|
|
name and member name to find the identifier. Alternatively, look at
|
||
|
|
the HTML source of a report and note the identifier (an HTML named anchor)
|
||
|
|
near the intended place for the comment.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
Adding links to comments can be accomplished in two ways: with the {@link} Javadoc tag, or by using HTML links directly.
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
|
||
|
|
<li>
|
||
|
|
To link to a class, use the package and class name, e.g. <nobr>{@link
|
||
|
|
packagename.classname}.</nobr>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>
|
||
|
|
To link to a specific method in a class' HTML page, use the package,
|
||
|
|
class name, a pound sign, and then the method and parameters, or ()
|
||
|
|
e.g. <nobr>{@link packagename.classname#methodname(params)}.</nobr>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>
|
||
|
|
To link to a specific constructor in a class' HTML page, use the package,
|
||
|
|
class name, a pound sign, and then the classname and parameters, or ()
|
||
|
|
e.g. <nobr>{@link packagename.classname#classname(params)}.</nobr>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>
|
||
|
|
To link to a specific field in a class' HTML page, use the package,
|
||
|
|
class name, a pound sign, and then the name of the field
|
||
|
|
e.g. <nobr>{@link packagename.classname#fieldname}.</nobr>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
Alternatively, you can use an explicit HTML
|
||
|
|
<a> element. e.g.
|
||
|
|
<nobr><a href="packagename.classname.html#methodname">link text<a></nobr>.
|
||
|
|
The specific HTML named anchor can be found by looking at the HTML
|
||
|
|
source of a report.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
Sometimes you may want to have the same comment text appear in
|
||
|
|
multiple places in the report. You can do this by having multiple
|
||
|
|
<identifier> elements in a single <comment> element. This
|
||
|
|
grouping does not persist after the comments file is regenerated.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
The first sentence from a comment in the source code for an element is
|
||
|
|
available in the comments XML file by using the @first tag. This tag
|
||
|
|
will be replaced (once) in the comments in the report by the first
|
||
|
|
sentence from the appropriate Javadoc comment.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<br><hr><br>
|
||
|
|
|
||
|
|
<H2><A NAME="troubleshooting"></A>TROUBLESHOOTING</H2>
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
<TABLE border="1" width="80%">
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top" align="center"><b>PROBLEM</b></TD>
|
||
|
|
<TD VALIGN="top" align="center"><b>POSSIBLE SOLUTION</b></TD>
|
||
|
|
</TR>
|
||
|
|
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top"><pre>Error: two projects are needed, one
|
||
|
|
<old> and one <new></pre></TD>
|
||
|
|
<TD VALIGN="top">The Ant JDiff task needs Ant 1.6.1 to work correctly</TD>
|
||
|
|
</TR>
|
||
|
|
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">You are not connected to the Internet, or are behind a firewall</TD>
|
||
|
|
<TD VALIGN="top">See the <a href="#baseURIoption">documentation</a> for how to use
|
||
|
|
the <code>-baseURI</code>
|
||
|
|
optionThis only applies to generating JDiff output,
|
||
|
|
not to viewing it.</TD>
|
||
|
|
</TR>
|
||
|
|
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">No changes are seen in the report.</TD>
|
||
|
|
<TD VALIGN="top">By default, Javadoc and JDiff only show public
|
||
|
|
and protected classes and members.</TD>
|
||
|
|
</TR>
|
||
|
|
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">No changes seen for package and private classes.</TD>
|
||
|
|
<TD VALIGN="top">Enable both the correct Javadoc visibility level
|
||
|
|
(-public, -protected, -package, -private) and the correct JDiff
|
||
|
|
visibility level (-excludeclass, -excludemember).</TD>
|
||
|
|
</TR>
|
||
|
|
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">No comments were inserted for packages.</TD>
|
||
|
|
<TD VALIGN="top">You need to use the <code>-sourcepath</code> argument to
|
||
|
|
locate the source code files, so that
|
||
|
|
JDiff can deduce where the <code>package.html</code> file with
|
||
|
|
comments about the package may be. If no <code>package.html</code>
|
||
|
|
file exists or can be found, then no comments can be suggested
|
||
|
|
for packages. Of course, comments can still be
|
||
|
|
<a href="#addingcomments">added by hand</a>.</TD>
|
||
|
|
</TR>
|
||
|
|
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">JDiff takes a long time to load XML, or throws
|
||
|
|
<code>java.net.NoRouteToHostException: Operation timed out</code>.</TD>
|
||
|
|
<TD VALIGN="top">The validation portion of loading the XML file
|
||
|
|
currently requires the ability to make an HTTP connection. Check
|
||
|
|
your network and try again, or see the <code>-baseURI</code>
|
||
|
|
option and the next suggestion.</TD>
|
||
|
|
</TR>
|
||
|
|
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">From behind a firewall,
|
||
|
|
<A NAME="troubleshootingFirewall"></A>
|
||
|
|
JDiff fails to load one of the required XML DTD files.</TD>
|
||
|
|
<TD VALIGN="top">Use the following settings to tell the Java2 VM
|
||
|
|
that you are behind a firewall:<br>
|
||
|
|
<code><nobr>java -DproxySet=true -DproxyHost=PROXYSERVER</nobr><nobr> -DproxyPort=PORT</nobr></code><br>
|
||
|
|
where <code>PROXYSERVER</code> is the hostname or IP address of
|
||
|
|
your proxy server, and <code>PORT</code> is the port number of the
|
||
|
|
proxy server.<br><br>
|
||
|
|
The other alternative is to use the local copies of the required
|
||
|
|
files by using the option <code>-baseURI</code> when generating the API XML
|
||
|
|
files. For example, <code>-baseURI "file:///C:/jdiff/lib"</code> would cause
|
||
|
|
the XML parser to use the copies which are shipped in the
|
||
|
|
<code>lib</code> directory, if JDiff is installed in
|
||
|
|
<code>C:\jdiff</code>. Note that there are <i>three</i> forward slashes
|
||
|
|
after "file:".
|
||
|
|
The <code>-baseURI</code> approach has the advantage that it
|
||
|
|
requires <i>no</i> connectivity to the Internet to be able to run JDiff.
|
||
|
|
</TD>
|
||
|
|
</TR>
|
||
|
|
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">JDiff fails to handle <code>assert</code> in J2SE1.4</TD>
|
||
|
|
<TD VALIGN="top">Be sure to use the <code>-source 1.4</code> argument to
|
||
|
|
Javadoc to handle assertions present in J2SE1.4 source code.
|
||
|
|
</TD>
|
||
|
|
</TR>
|
||
|
|
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Using an XML parser other than Xerces</TD>
|
||
|
|
<TD VALIGN="top">Set the <code>org.xml.sax.driver</code> system property to
|
||
|
|
the name of the XML parser class which you wish to use. Setting a system
|
||
|
|
property is usually done by passing <nobr><code>-Dname=value</code></nobr> to the JVM.
|
||
|
|
To cause Javadoc to pass an argument to the underlying JVM, use
|
||
|
|
<code>-J-Dname=value</code>. To pass an argument to Javadoc from within
|
||
|
|
an ANT Javadoc task, use the <code>additionalparam</code> attribute, e.g.
|
||
|
|
<nobr><code>additionalparam="-J-Dorg.xml.sax.driver=com.example.my.driver"</code><nobr>
|
||
|
|
</TD>
|
||
|
|
</TR>
|
||
|
|
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Comparing Jar files results in duplicate class
|
||
|
|
changes being reported.</TD>
|
||
|
|
<TD VALIGN="top">Be sure to use the <code>-packagesonly</code>
|
||
|
|
option when using Jar files as the input to JDiff. You should not
|
||
|
|
need to use <code>-packagesonly</code> otherwise.
|
||
|
|
</TD>
|
||
|
|
</TR>
|
||
|
|
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Documentation difference page becomes all changes
|
||
|
|
part way through.</TD>
|
||
|
|
<TD VALIGN="top">This problem can occur if incorrect HTML is
|
||
|
|
written in the new documentation. JDiff shows this HTML on the
|
||
|
|
documentation difference page, and can cause entries later on in
|
||
|
|
the page to be displayed incorrectly.
|
||
|
|
|
||
|
|
<p>One solution is to edit the documentation difference page by
|
||
|
|
hand, but the better solution is to fix the offending HTML in the
|
||
|
|
new source code.
|
||
|
|
</TD>
|
||
|
|
</TR>
|
||
|
|
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">The background color of my HTML report is not correct.</TD>
|
||
|
|
<TD VALIGN="top">Check that the file <code>background.gif</code> from the <code>lib</code> is in the same directory as the <code>changes.html</code> file.
|
||
|
|
</TD>
|
||
|
|
</TR>
|
||
|
|
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">The names of exceptions are too long in the HTML report.</TD>
|
||
|
|
<TD VALIGN="top">To use short names for exceptions, set the
|
||
|
|
<code>showExceptionTypes</code> boolean to <code>false</code> in
|
||
|
|
<code>XMLToAPI.java</code> file and recompile.
|
||
|
|
</TD>
|
||
|
|
</TR>
|
||
|
|
|
||
|
|
</TABLE>
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
|
||
|
|
<H2><A NAME="errorswarnings"></A>ERRORS AND WARNING MESSAGES</H2>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
The warnings and error messages which can be generated by JDiff are as
|
||
|
|
follows:
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
<TABLE border="1">
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top" align="center" width="25%"><b>ERROR MESSAGE</b></TD>
|
||
|
|
<TD VALIGN="top" align="center"><b>POSSIBLE CAUSE</b></TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Error: unknown element type.</TD>
|
||
|
|
<TD VALIGN="top">The XML file contains an element tag which the
|
||
|
|
current version of JDiff cannot recognize. This may occur if an
|
||
|
|
older version of JDiff is used with XML files generated by a newer
|
||
|
|
version.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Error: IO Error while attempting to create <i>X</i>.</TD>
|
||
|
|
<TD VALIGN="top">Java was unable to open a file for writing. May
|
||
|
|
occur if the user does not have write permission for the current
|
||
|
|
directory.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Error: no identifier found in the comments XML file.</TD>
|
||
|
|
<TD VALIGN="top">The XML file for the comments for the report must
|
||
|
|
contain an identifier to indicate which report of differing APIs
|
||
|
|
these comments are written for.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Error: unknown program element type.</TD>
|
||
|
|
<TD VALIGN="top">Internal JDiff error.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Error: could not create the subdirectory <i>X</i>.</TD>
|
||
|
|
<TD VALIGN="top">Java was unable to create a directory. May
|
||
|
|
occur if the user does not have write or execute permission for the current
|
||
|
|
directory.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Error: file <i>X</i> does not exist for the [old|new] API.</TD>
|
||
|
|
<TD VALIGN="top">The XML files corresponding to the names given to
|
||
|
|
<code>-oldapi</code> and <code>-newapi</code> are not in the
|
||
|
|
current directory. This may be because the XML files have not yet been
|
||
|
|
generated, or were generated elsewhere.<br>
|
||
|
|
It can also occur if the
|
||
|
|
XML file was generated with one API identifier, and is now being
|
||
|
|
read in with another identifier. Either use the same identifier,
|
||
|
|
or change the <api> name element value in the XML file to the new
|
||
|
|
API identifier.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Error: no API identifier found in the XML file <i>X</i>.</TD>
|
||
|
|
<TD VALIGN="top">The given XML file does not have an identifier in
|
||
|
|
it, probably due to manual modification.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Error: no packages found in the APIs.</TD>
|
||
|
|
<TD VALIGN="top">JDiff was unable to find any packages in the
|
||
|
|
arguments given to Javadoc.</TD>
|
||
|
|
</TR>
|
||
|
|
</TABLE>
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
<TABLE border="1">
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top" align="center" width="25%"><b>WARNING MESSAGE</b></TD>
|
||
|
|
<TD VALIGN="top" align="center"><b>POSSIBLE CAUSE</b></TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Warning: illegal string found in text. Ignoring the comment.</TD>
|
||
|
|
<TD VALIGN="top">The suggested comments from Javadoc are stored in
|
||
|
|
XML files in a CDATA element, which permits every string except .</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Warning: no difference between the APIs.</TD>
|
||
|
|
<TD VALIGN="top">There was no difference between the APIs. You are
|
||
|
|
probably comparing two identical XML files.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Warning: no classes found in the package <i>X</i>.</TD>
|
||
|
|
<TD VALIGN="top">A package without classes was encountered.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Warning: change from deprecated to undeprecated for class <i>X</i>.</TD>
|
||
|
|
<TD VALIGN="top">A class changed from being deprecated to being
|
||
|
|
undeprecated in the next release. This is usually either poor
|
||
|
|
software design or a misplaced @deprecated Javadoc tag.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Warning: change from deprecated to undeprecated
|
||
|
|
for a constructor in class <i>X</i>.</TD>
|
||
|
|
<TD VALIGN="top">A constructor changed from being deprecated to being
|
||
|
|
undeprecated in the next release. This is usually either poor
|
||
|
|
software design or a misplaced @deprecated Javadoc tag.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Warning: change from deprecated to undeprecated for method <i>X</i>.</TD>
|
||
|
|
<TD VALIGN="top">A method changed from being deprecated to being
|
||
|
|
undeprecated in the next release. This is usually either poor
|
||
|
|
software design or a misplaced @deprecated Javadoc tag.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Warning: text of comment does not end in a period.</TD>
|
||
|
|
<TD VALIGN="top">Generated when the <code>-checkcomments</code> is
|
||
|
|
used. The suggested comment does not end in a period, question mark or exclamation mark.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Warning: <i>N</i> identical ids in the existing comments file. Using the first instance.</TD>
|
||
|
|
<TD VALIGN="top">The comments file contains comment for multiple
|
||
|
|
places in the report, but <i>N</i> of the identifiers for the comment
|
||
|
|
are non-unique.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Warning: incorrectly formatted @link in text.</TD>
|
||
|
|
<TD VALIGN="top">JDiff was unable to parse the @link in the
|
||
|
|
suggested comment.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Warning: comment <i>com.acme.sp</i> is no longer used.</TD>
|
||
|
|
<TD VALIGN="top">The comment in the comments file intended for the
|
||
|
|
given element is no longer needed, since the element is no longer
|
||
|
|
part of the changes between the APIs. The comment will be moved to
|
||
|
|
the end of the comments file and preserved, but not used.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Warning: API identifier in the comments XML file differs from the name of the file.</TD>
|
||
|
|
<TD VALIGN="top">The comments file keeps track of which APIs it is
|
||
|
|
to be used for, and has detected a mismatch with the names of the
|
||
|
|
current APIs.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Warning: multiple @deprecated tags found in comments for <i>X</i>. Using the first one only.</TD>
|
||
|
|
<TD VALIGN="top">A comment with more than one @deprecated tag was
|
||
|
|
encountered in the source code. This is considered poor Javadoc style.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Warning: @ tag seen in comment.</TD>
|
||
|
|
<TD VALIGN="top">An @ tag other than @link has somehow made its
|
||
|
|
way into a suggested comment. This should not occur, but can be
|
||
|
|
remedied by editing the comments file to use a different comment.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Warning: duplicate class : <i>X</i> found. Using the first instance only.</TD>
|
||
|
|
<TD VALIGN="top">Multiple instances of the same fully qualified
|
||
|
|
class name were found in the API XML file. Most likely caused by
|
||
|
|
manual modification of the file after it was generated.</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Warning: missing @since tag</TD>
|
||
|
|
<TD VALIGN="top">A class, constructor, method or field was added
|
||
|
|
in the later API but no @since tag was found in the Javadoc
|
||
|
|
comment. This information is logged into a file
|
||
|
|
<code>missingSinces.txt</code> in the same directory as
|
||
|
|
<code>changes.html</code>. This file is informational only. The
|
||
|
|
boolean to control this behaviour is in the source file
|
||
|
|
<code>HTMLIndexes.java</code>.
|
||
|
|
</TD>
|
||
|
|
</TR>
|
||
|
|
<TR>
|
||
|
|
<TD VALIGN="top">Warning: API identifier in the XML file <i>X</i> differs from the name of the file <i>Y</i>.</TD>
|
||
|
|
<TD VALIGN="top">The name given to <code>-apiname</code> when the XML file
|
||
|
|
is generated is embedded in the XML file as a top-level attribute. This
|
||
|
|
warning suggests that the XML file has been modified by hand, but that
|
||
|
|
report generation should proceed using the new API identifier.</TD>
|
||
|
|
</TR>
|
||
|
|
</TABLE>
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
|
||
|
|
<H2><A NAME="differencestatistics"></A>DIFFERENCE STATISTICS</H2>
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
During the generation of a report, JDiff also reports a percentage
|
||
|
|
difference between the two APIs being compared, e.g. "Approximately
|
||
|
|
10% difference between the APIs". This statistic is calculated in the
|
||
|
|
following way:
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
Percentage change = 100 * (added + removed + 2*changed)
|
||
|
|
-----------------------------------
|
||
|
|
sum of public elements in BOTH APIs
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
So if there are 15 packages in the old API, and 2 of these are removed,
|
||
|
|
and 17 packages in the new API, 1 of which is newly added, and only 3
|
||
|
|
of which have changed, then the simple percentage difference would be:
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
100 * (1 + 2 + 2*3)/ (15 + 17) = 28%
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
A change of 100% means that there are no packages in common between
|
||
|
|
the two APIs. A change of 0% indicates that nothing changed between
|
||
|
|
the two APIs. This formula is applied recursively in JDiff for classes
|
||
|
|
and their members. That is, the value for the number of packages
|
||
|
|
changed is not an integer, but instead is the value obtained by
|
||
|
|
applying the same formula to the all the classes in the changed
|
||
|
|
packages, and then to all the members of the changed classes.
|
||
|
|
This results in a lower, but more accurate, percentage difference.
|
||
|
|
The percentage difference value does not appear anywhere in the HTML
|
||
|
|
report files generated by JDiff.
|
||
|
|
The test suite for JDiff v1.0 had a difference value of approximately 63%.
|
||
|
|
A real-world value is the value for the differences between J2SE1.2 and
|
||
|
|
J2SE1.3, which is approximately 8%.
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
|
||
|
|
<H2><A NAME="limitations"></A>LIMITATIONS</H2>
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
<ol>
|
||
|
|
<li>While Java is highly backward compatible, so that, for example,
|
||
|
|
the XML for a
|
||
|
|
J2SE1.2 application can be generated using JDiff with J2SE1.3, there
|
||
|
|
are a few cases where classes will appear in the XML of the API which are
|
||
|
|
not present in the source code. These classes appear to be inserted by
|
||
|
|
<code>javac</code> or <code>javadoc</code>. An example of this is the class
|
||
|
|
<code>java.awt.Robot</code>, which is inserted into the XML for
|
||
|
|
J2SE1.2 if <code>javadoc</code> in J2SE1.3 is used, but not does not appear in
|
||
|
|
the XML if <code>javadoc</code> in J2SE1.2 is used.<br>
|
||
|
|
To avoid these (rare) cases, it is recommended that you <i>use the same version
|
||
|
|
of the J2SE that the application was written for</i>.</li>
|
||
|
|
<li>JDiff does not tell you how two Javadoc web pages differ in layout, though
|
||
|
|
it can tell you how the content has changed.
|
||
|
|
Nor does it
|
||
|
|
compare what the methods in an API do; if JDiff could tell you what had changed about the way two
|
||
|
|
versions of an API execute, the <a
|
||
|
|
href="http://en.wikipedia.org/wiki/Halting_Problem">Halting
|
||
|
|
Problem</a> would be solved, and our lives would be very different.</li>
|
||
|
|
<li>On a P3 450MHz machine, to scan all of the J2SE <code>Java</code>
|
||
|
|
and <code>javax</code> packages and generate XML takes about 2 minutes
|
||
|
|
per version. To generate a report from the XML files takes about 30s</li>
|
||
|
|
</ol>
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
|
||
|
|
<H2><A NAME="furtherreading"></A>FURTHER READING</H2>
|
||
|
|
|
||
|
|
<BLOCKQUOTE>
|
||
|
|
<UL>
|
||
|
|
<LI><A HREF="http://www.sys-con.com/java">Java Developer's Journal
|
||
|
|
</A>, April 2002 contained an article about JDiff. The article
|
||
|
|
can also be <a
|
||
|
|
href="http://javadiff.cvs.sourceforge.net/*checkout*/javadiff/jdiff/doc/JDiffArticle.pdf">found
|
||
|
|
here</a>.</LI>
|
||
|
|
<LI><A HREF="http://java.sun.com/j2se/javadoc/">Javadoc</A> and Doclet
|
||
|
|
documentation from Sun.</LI>
|
||
|
|
<LI><A HREF="http://java.sun.com/j2se/javadoc/faq.html#doclets">Third-party
|
||
|
|
doclets</a> as listed by Sun.</LI>
|
||
|
|
<LI><A HREF="http://www.doclet.com">Third-party doclets</a> as listed by others.</LI>
|
||
|
|
</UL>
|
||
|
|
|
||
|
|
</BLOCKQUOTE>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
This software comes with absolutely NO WARRANTY. See the LGPL in the file <a href="http://javadiff.cvs.sourceforge.net/*checkout*/javadiff/jdiff/LICENSE.txt">LICENSE.txt</a> for
|
||
|
|
details.
|
||
|
|
</center>
|
||
|
|
|
||
|
|
<p align="center">
|
||
|
|
<font size="-1">
|
||
|
|
Copyright © 2001-2007 <a href="mailto:mdoar@pobox.com">Matthew B. Doar</a><br>
|
||
|
|
</font>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
</BODY>
|
||
|
|
</HTML>
|