ICU-3743 split icu4j api data gathering from report generation

X-SVN-Rev: 15270

icu4j/src/com/ibm/icu/dev/tool/docs/README.txt

@@ -0,0 +1,87 @@
+-------------------------------------------
+Using the GatherAPIData and ReportAPI tools
+-------------------------------------------
+
+These two tools are used together to generate reports about changes in
+supported API between versions of ICU4J.
+
+
+GatherAPIData 
+
+GatherAPIData uses javadoc to process the ICU4J source files and
+generate a file listing information about the public API, including
+the ICU4J status (draft, stable, deprecated, obsolete).  It excludes
+private API, API marked @internal.  The file is written as text, so it
+is human-readable, but it is a bit verbose.  To save space, the file
+can be zip'd (NOTE: to become gzip'd), which will reduce the size by
+about a factor of 10.
+
+GatherAPIData requires javadoc and is currently based on sun jdk
+1.4.2.  JavaDoc is internal (I believe) so you need a reference jvm
+from Sun to compile the tool, but it can be run against any 1.4 JDK
+(at least, those from Sun).  Instructions in the source file show how
+it can be invoked.
+
+GatherAPIData should be passed all the packages that need reporting.
+Currently, public api is only in the lang, math, text, and util
+subpackages of com.ibm.icu.
+
+
+ReportAPI 
+
+ReportAPI takes two api files generated by GatherAPIData and reports
+on removals, changes, and additions to the API.  It does this by
+comparing the API information in the two API files.  When new classes
+are added, only the class is listed, not its entire API, and similarly
+when a class is deleted.  When APIs with the same name and signature
+are changed (visibility, status, inheritance) these changes are listed
+by showing the old and new versions of the API.
+
+ReportAPI is not particularly smart, and in particular, does not know
+about inherited API.  So for example, moving public API from a class
+to a base class is reported as a deletion of API from the original
+class, even though the effective API on the original class is
+unchanged by this.
+
+ReportAPI also does not know about Java class files, so for example it
+cannot be used to compare com.ibm.icu.lang.UCharacter against
+java.lang.Character.  This might be provided in a later release.
+
+For these reasons, in general it is best to compare two successive
+versions of ICU4J against each other, rather than radically different
+versions.  A large number of changes can show up, many of which might
+fall into these 'innocuous' categories.
+
+ReportAPI can generate either plain text or html reports.  Since it
+only requires the data files and does not rely on JavaDoc, it is more
+straightforward to invoke.
+
+
+API Data Files
+
+API Data files for ICU4J 2.8 and 3.0 are in this directory.  The
+intent is to store data files for each release version of ICU4J, to
+facilitate comparison using the ReportAPI tool.  Of course, they can
+always be regenerated using the GenerateAPI and the sources of a
+particular ICU4J release.
+
+The format of the API data file is straightforward.  The first line of
+the file is the header, successive lines are the api information.
+Each line consists of a number of tokens, each followed by a
+semi-colon (incuding the last token on the line).
+
+The header line contains the version number, the 'name' of the version
+of ICU4J represented by the file, and a 'base directory' field
+(currently not fully implemented).
+
+The following lines contain data generated by the APIInfo class, one
+line per class or method.  The tokens are status, visibility, static,
+final, synchronized, abstract, type, package, containing class, name,
+and 'signature' (which varies by the type of object).  For classes,
+the 'signature' is the immediate inheritance of the class.  For
+fields, the 'signature' is the type of the field.  For methods, the
+'signature' is the function signature. All fields are always present.
+
+For more information, please see APIInfo.java.
+
+-------