******************** * 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 =============