test/langtools/jdk/javadoc/tool/sampleapi/README.txt

            SampleAPI Generator for javadoc

1. General description

    The primary goal is to provide one or more data sets to be used as input
to the javadoc tool, such that it can be used to generate representative samples
of all the different content on all the different types of pages that can be
generated by javadoc.

    The tool is implemented as generator based on xml descriptions of data sets.
The xml description of data set provides top level entities (class, interface,
enum, annotation) with all possible content. Desired output parameters (fields,
methods, inner/nested classes) are also described in xml as lists of modifiers,
types and annotations. The generator "multiply" the entities from the lists
providing the set of all possible combinations.

    After the api generation the tool connects the javadoc style comments to
the generated entities with full possible sets of supported tags.

2. Tool structure

    Sources:
        test/tools/javadoc/sampleapi/lib - generator sources
        test/tools/javadoc/sampleapi/res/xml - sample data sets in xml
        test/tools/javadoc/sampleapi/res/txt - sample texts for doc comments

3. Public API

3.1 Command line runner

  * test/tools/javadoc/sampleapi/lib/sampleapi/SampleApiDefaultRunner.java

    class sampleapi.SampleApiDefaultRunner

  Options: [-?|-h|--help] [-o:<dir>|--outdir:<dir>]
    -?|-h|--help             - print help
    -o:<dir>|--outdir:<dir>  - set <dir> to generate output

3.2 Programmatic access

  * test/tools/javadoc/sampleapi/lib/sampleapi/SampleApi.java

    class sampleapi.SampleApi

    public void generate(File dir)
    public void generate(Path dir)
    public void generate(String dir)

3.3 How to run other xml data set description

  Put data set xml description into res/xml directory

  * test/tools/javadoc/sampleapi/lib/sampleapi/generator/PackageGenerator.java

    class sampleapi.generator.PackageGenerator

    public void processDataSet(String dsName)
    public void generate(File outDir)