A proposed javadiff doclet
843810Aug 4 2001 — edited Nov 2 2001(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