********************
* JDiff Work Items *
********************
KNOWN BUGS
==========
BUG: JDiff doesn't expand @docroot doc tags in Javadoc1.4
BUG: Handling of @link tags in the first sentence of comments is not as
general as it should be. See convertAtLinks() comments.
MINOR BUG: @links to methods may not be expanded properly if we don't have the
signature in the @link. This only happens once (at invoke) in J2SE1.2/1.3,
and the link goes to the right page, just not the right named anchor.
Pretty rare.
BUG? The MergeChanges code may not be transferring all change information into
the MemberDiff for methods and fields?
DESIGN
======
Short Term:
----------
Add an option for verbose output?
Add an option to redirect output to a log file?
Does not check when there is a change in the class in which a locally defined
method is overriding another method.
Statistics - is a change in inheritance for a method or field really equivalent to one add and one delete in all cases?
org.omg.CORBA.AnySeqHelper is generated by javac or javadoc using J2SE1.3 on
in J2SE1.2,
so has no documentation at the Sun website. Same for J2SE1.4 with org.omg.CosNaming.BindingIteratorPOA.html. This is probably due to the issue now noted in the "Limitations" section in jdiff.html.
No longer need the lib/TR directory - files can be deleted
Generating EJB1.2 to EJB1.2 there is an added constructor with multiple
parameters whose Javadoc named anchor has no space in it, but other such
constructors do. This produces a link to the top of the page rather than the
correct place. Same with the Servlet report.
538102. A developer may not want to show changes from
native to non-native, etc, since this is really
an implementation detail. An easy way to select
what is shown would be useful.
548382. Separate class and interface information might be useful,
since Javadoc does so.
476310. There are some cases where a doc change is the only change.
Should this really count towards the API % change?
Create an ANT script instead of prepare_release.bat
Create a top-level ANT script.
Long Term:
---------
549926 - add ability to emit XML representation of the changes, which can then
be transformed into HTML.
Ship .gz and .tar?
Better end of sentence detection for annotations - use the J2SE14 approach?
Support inherited exclusion in RootDocToXML.java
Refactor code in Diff.java to avoid duplication
Better setting of trace per module
Add a color square to indicate how much a package or class changed
Add interactive ability with jdiff.JDiff for easiest use?
Add progress bars for the longer parts of the program?
Does Javadoc add "()" for links to methods with no arguments? It does
now, but perhaps it did not with J2SE1.2 javadoc?
ant.bat is a complex script for all windows platforms - could be useful
icontrol and ant page at has helpful info for a JavaUI and ANT task
http://icplus.sourceforge.net/dbc_example.html
How to find which classes are documented in a J2SE release, since it is
a subset of of the source classes shipped.
[All files marked as 404 (not found) by Xenu should have their packages
removed from the list scanned when generating the XML. E.g.
http://java.sun.com/j2se/1.3/docs/api/java/awt/dnd/peer/DragSourceContextPeer.html
http://java.sun.com/j2se/1.3/docs/api/java/text/resources/DateFormatZoneData.html
These packages are not documented in the J2SE1.3.]
Reduce the memory usage with large APIs
Use -linksource in tests with J2SE1.4. (Source info is now in the XML)
Break up the XML file into smaller files?
Sometimes "changed" is not linked but documentation is noted as having
changed because the documentation was inherited from a superclass.
Break out subclasses in DiffMyers.java for jar files?
In Javadoc generated HTML, the methods and fields which are inherited
from a parent do not have named anchors for the JDiff to link to them. This
means that the links go to the correct child class, but the user has to look
in the inherited methods and fields sections to find the right element.
This was fixed by checking for the case in HTMLReportGenerator, but the tricky
case, which is not checked for, is the case with inner classes and methods or
fields moving to their parent class. In this case, the class will be
correct, but the link will take you to the top of the page, rather than the
actual method.
Add support for differences for other languages - create base classes,
generalize XML.
The comment data in the deprecated attribute should really be in a CDATA
section to avoid having to hide the HTML tags. But his would mean that the
attribute deprecated would become an element and be harder to parse
the text out.
Add ability to specify the location of the generated XML file?
Add a "jdiff_" prefix to all generated HTML files to clearly distinguish them
from Javadoc generated files?
Good to add support for Notes - force altered classes etc recorded in user_comments.xml to appear
Break HTMLReportGenerator up into at least two files
Should have added new class to ClassDiff etc? Tidy up where possible.
Constructor params should be elements?
Define accessor methods for _ vars
Use a modifiers field instead of separate modifiers in XML to save space?
Add a name_ field to the ConstructorAPI class? Or a common superclass?
The final comparison call to Javadoc could be a separate Java program, but it
seems more obvious to use Javadoc there too. Also provides the future ability
to scan the current product at the same time as comparing it, reducing three
steps to two.
The index files are quite large with J2SE14 - 1.7MB for an HTML file.
Provide an option to include the sub-totals with the statistics table?
TESTS
=====
More checking of excludeTag with "@docset Internal" works, or however the tag
value is defined in J2SE1.4
Test change from a class to an interface
Test interfaces more
Test very long names
Test changes in deprecation at a class level
Test @first again
Test @link with all different formats
Test comments, multiple ids and the warning of multiple identical ids
Test that identifiers with spaces work
Test classes with no packages
Check that the comments file tests correctly for the correct APIs
Test case of a package and a class having the same name
Test case of moving a method into a superclass and vice versa
Test nested class definitions more closely
Test moving methods and fields from one superclass to another
Test @value changes
Compare new test results to old test results to check parent/child work
DOCUMENTATION, BUILD AND EXAMPLES
=================================
Examples:
---------
Add more changes
Documentation:
-------------
Example of writing your own comments for the report
Developers' notes: TODO is must, OPTION is maybe
REPORT PRESENTATION
===================
Add the ability to use the API names in the -doctitle and -windowtitle options
Add the ability to add a watermark, default "Internal", to the generated pages
Minor: when only one kind of change exists in an index, then that one
choice should be prechosen and highlighted.
Update all the error and warning messages in jdiff.html
Better text demo of showing all private changes in APIs
Fix the small size of old and new links
Add ability to have no newjavadoc links either
Better presentation of all the documentation changes? Perhaps sorted?
Run HTML checker on all generated HTML files - no errors
- some warnings about <span> elements mixed with <blockquote>, due to
a combination of diffing HTML with using HTML output
and others still to fix, using tidy and the tests:
Warning: html doctype doesn't match content
Warning: <nobr> is probably intended as </nobr>
1 ChangedPackage.ChangedMethods.html:92:156: Warning: replacing unexpected </nobr> by </code>
1 ChangedPackage.ChangedMethods.html:71:187: Warning: discarding unexpected </nobr>
1 ChangedPackage.ChangedMethods.html:71:179: Warning: trimming empty <nobr>
Avoid single letter indexes with just one entry on a new line
If a return type has a [] in it, browser may break the line before the []
Maybe the table should be name and a row under it for the description , to stop cramped names and descriptions?
Add note that links in docdiffs may not necessarily work, since some of them
are written expecting to be in documents in the Java API tree.
Add a "having problems?" page?
MISCELLANEOUS
=============
