A proposed javadiff doclet
(Also sent to javadoc-tool@sun.com)
When dealing with multiple releases, it is often very useful to be able to document exactly what has changed in the public API between different releases. A useful tool to do this could be built using the existing Javadoc doclet architecture.
I envision something like:
javadoc -doclet tools.doclets.docdiff.DocDiff -sourcePath /rel_1/src \
-docletpath ... -sourceId "Release 1.0" \
packages...
This command would run the proposed DocDiff doclet to produce a file, Release_1.0.sum, which would contain an ASCII summary of the APIs for the given set of source file. The usual collection of arguments to specify what is part of a public API could be passed in too. ASCII would make it easy to check in the .sum file, but binary could be used if the ASCII files were too large.
Then the DocDiff doclet would be run again but this time pointing to a different collection of source code, and also with a -compare argument, which would have the value of some previous -sourceId argument, e.g.
javadoc -doclet tools.doclets.docdiff.DocDiff -sourcePath /rel_11/src \
-docletpath ... -sourceId "Release 1.1" -compare "Release 1.0" \
packages...
This would read the new set of source files, generate a Release_1.1.sum file for them, but it would also read in the previously generated Release_1.0.sum file. The additions, removals and changes (including deprecations) between the releases could then be determined, and an HTML summary generated. Suitable links to the javadoc pages for each class could appear in the HTML summary.
If only I had the time to do this. Thoughts?
~Matt
doar@pobox.com
[1730 byte] By [
mdoar] at [2007-9-26 2:59:24]
This would be an interesting and useful doclet.
However, when we first needed to diff javadoc, we went in search
of existing HTML diff tools. We found a tool developed by
ATT/BellLabs/Lucent called TopBlend, which generates HTML
pages showing diffs from pairs of HTML pages. Added entries
are underlined and deleted entries are struck through.
An example of The JCP maintenance review for merlin beta is at
http://java.sun.com/j2se/1.4/jcp/j2se-1_4-mr_docs-spec/apidiffs/index-diffs.html
This page can be reached from the very bottom of:
http://java.sun.com/j2se/1.4/jcp/j2se-1_4-mr_docs-spec/
TopBlend is under evaluation, and does not appear to be publicly
available (yet?). Contact javadoc-tool@sun.com if you want the name of a contact.
-Doug
Interesting. Good looking output. But what happens when you decide to change the format of the HTML output? Seems to me that this assumes that the HTML template is frozen for all time.~Matt
mdoar at 2007-6-29 10:55:23 >
When the format of the HTML changes in javadoc, then you would need to re-generate the docs.
Using TopBlend has the constraint that you should run the same version of javadoc on both sets of source code so that any differences will be due only to the source code and not due to the HTML format.
-Doug Kramer
Javadoc team
I have a comletely approach to the javadoc and to many of the proposed issues. I have created a dynamic javadoc which creates its pages via a database rather than building html pages when the javadoc tool is run.
This allows me to setup constraints ie only showing elements which are within a certain version number range (denoted by @version)
I have not programmed the above feature, but I think that within reasonable time this could be implemented. Would that be a solution to your problem?
Maybe, but would it track the smallest changes in an API, such as a change of type or method name change?
mdoar at 2007-6-29 10:55:23 >
This doclet, named JDiff, was released today at http://sourceforge.net/projects/javadiff/The JDiff homepage has examples of the output.~Mattdoar@pobox.com
mdoar at 2007-6-29 10:55:23 >
JDiff1.0.3 has been released at http://sourceforge.net/projects/javadiff/
Major changes for this release are:
+ Better tracking of documentation changes.
+ More statistical information.
+ Ported to JDK1.4.
The results of comparing JDK1.3 and JDK1.4B2 are now available from the JDiff homepage or at
http://javadiff.sourceforge.net/jdiff/jdkchanges2/changes.html
See the changes below for details of bugs fixed.
~Matt
doar@pobox.com
Changes:
1.0.3
Fixed bugs in tracking package and class-level documentation changes.
Fixed bugs in tracking documentation changes at the constructor,
method and field level.
Fixed a bug in indexes links to default constructors which had changed
Fixed a bug that -nodocchanges did not behave as expected
Fixed a bug in converting @link tags to HTML links, but some broken
links remain.
Fixed bug 472529 (updated documentation for new options)
Fixed bug 472703 (background color is weird)
Fixed bug 476930 (HTML tables need in some places)
Added feature request 476946 (location of user comments file)
Added feature request 476201 (Need more statistics) by creating the
-stats option which generates a statistics page in the report.
Added feature request 476202 (Port to JDK1.4)
Improved merging of additions and removals into changes for methods.
Better display of elements which start with underscores in indexes
mdoar at 2007-6-29 10:55:23 >
