Package de.kruis.padoclet

You probably know the difference between the public API and the published API.

See:
          Description

Class Summary
FilterDocletBase This class is a base class for javadoc filter doclets.
FilterDocletBase.ComparableHandler This class is the base of all the HalfDynamicProxy classes for the javadoc *Doc interfaces.
FilterDocletBase.DH This class is used to perform a lazy instantiation of the delegate / formating doclet class.
FilterDocletBase.HandlerBase This class is the base of all the HalfDynamicProxy classes for the javadoc interfaces.
FilterDocletBase.Option Option handling for doclets.
PublishedApiDoclet This class is a java 1.5 doclet, that is used as a filter between the javadoc framework and another doclet, that produces some output.
PublishedApiDoclet.AnnotationDescHandler Proxy methods for AnnotationDesc instances.
PublishedApiDoclet.AnnotationTypeDocHandler Proxy methods for ClassDoc instances.
PublishedApiDoclet.ClassDocHandler Proxy methods for ClassDoc instances.
PublishedApiDoclet.DocHandler Proxy methods and state common to all Doc instances.
PublishedApiDoclet.MethodDocHandler Proxy methods for the MethodDoc instance.
PublishedApiDoclet.PackageDocHandler Proxy methods for PackageDoc instances.
PublishedApiDoclet.RootDocHandler Proxy methods for the RootDoc instance.
RefCheckDoclet This doclet creates warnings for references to undocumented items.
RefCheckDoclet.Option Option handling for doclets.
 

Package de.kruis.padoclet Description

You probably know the difference between the public API and the published API. The former is the set of classes, interfaces, methods, fields etc., that can be used from a technical point of view. The later is the set of classes, interfaces, methods, fields etc., that is intended to be used by a third party. While you can change the public API using the refactorings provided by your IDE, you can't change the published API without breaking third party code. Therefore the published API will be a (somethimes rather small) subset of the public API. There is an elaborate paper about all that from Martin Fowler: "Public versus Published Interfaces" (IEEE Software, March/April 2002, p.18f, online available at http://martinfowler.com/ieeeSoftware/published.pdf)

Unfortunately javadoc doesn't support the concept of a published API. The PublishedApiDoclet tries to leverage this deficiency. It acts as a filtering proxy or decorator for another doclet, that formats the output. The PublishedApiDoclet hides anything, that doesn't belong to the published API from the formating doclet.

Usage:

The PublishedApiDoclet follows the javadoc doclet conventions. That is, you need to add the parameters -doclet de.kruis.padoclet.PublishedApiDoclet and -docletpath /path/to/PublishedApiDoclet.jar to your javadoc command line. Then you have to set the system property PublishedApiDoclet.delegate to the name of the formating doclet, unless you use the javadoc standard doclet. (A system property is used, because the PublishedApiDoclet needs the name of the formating doclet to parse the command line.) Several command line options controll the behaviour of the PublishedApiDoclet. Use the option -padHelp to get an overview over the options.

Unfortunately, I didn't write a more complete documentation yet. But have a look at the example subpackage.