mirror of
https://github.com/overcuriousity/autopsy-flatpak.git
synced 2025-07-06 21:00:22 +00:00
237 lines
8.2 KiB
Plaintext
237 lines
8.2 KiB
Plaintext
********************
|
|
* 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
|
|
=============
|