Automated Operator Documentation

Both presented tools need the tools.jar shipped with the SUN JDK.
In Maven this dependency can be included by adding the following snippet in the dependencies section of the pom.

<dependencies>
...
  <dependency>
    <groupId>com.sun</groupId>
    <artifactId>tools</artifactId>
    <version>1.6.0</version>
    <scope>system</scope>
    <systemPath>${java.home}/../lib/tools.jar</systemPath>
  </dependency>
...
</dependencies>

Doclet API

The Doclet API can be used to generate documentation based on the source code. It's also used for Javadoc generation, so it's also called Javadoc API.

Writing Doclets

It's easy to write your own Doclet.

"Example Doclet"

import com.sun.javadoc.*;

public class ListParams extends Doclet {

    public static boolean start(RootDoc root) {
        ClassDoc[] classes = root.classes();
        for (int i = 0; i < classes.length; ++i) {
            ClassDoc cd = classes[i];
            printMembers(cd.constructors());
            printMembers(cd.methods());
        }
        return true;
    }

    static void printMembers(ExecutableMemberDoc[] mems) {
        for (int i = 0; i < mems.length; ++i) {
            ParamTag[] params = mems[i].paramTags();
            System.out.println(mems[i].qualifiedName());
            for (int j = 0; j < params.length; ++j) {
                System.out.println("   " + params[j].parameterName()
                    + " - " + params[j].parameterComment());
            }
        }
    }        
}

The static start(RootDoc root) method serves as the entry point for the Doclet, like main(String[] args) for applications.
As parameter it gets an instance of the RootDoc class. The object provides all information needed for this run of the Doclet.

Run a Doclet

To execute your Doclet you have to call javadoc with the fully qualified class name to your Doclet-class as parameter.

"Executing a Doclet"

javadoc -doclet <DocletClassName> -sourcepath <SourcePath> -classpath <ClassPath> <Package>

Parameter	Description
-doclet <DocletClassName>	The fully qualified class name of the doclet to be used.
-sourcepath <SourcePath>	Path to the source files.
-classpath <ClassPath>	Path to the compiled class files.
<Package>	The fully qualified package name to be processed.

Links

Doclet API
Javadoc Tool
Example Impl. for Operators

Annotation Processing Tool

This tool is specialized on the processing of annotation, as the name says.
Compared to the Doclet API it has the following it has the following advantages.

has a cleaner model of the declarations and current type structure of programs
uses a more contemporary API design, such as returning generic collections instead of arrays and providing visitors to operate on declarations and types
supports recursive processing of newly generated files and can automatically cause compilation of original and generated source files

Write an Annotation Processor

"Example Annotation Processor"

import com.sun.mirror.apt.*;
import com.sun.mirror.declaration.*;
import com.sun.mirror.type.*;
import com.sun.mirror.util.*;

import java.util.Collection;
import java.util.Set;
import java.util.Arrays;

import static java.util.Collections.*;
import static com.sun.mirror.util.DeclarationVisitors.*;

/*
 * This class is used to run an annotation processor that lists class
 * names.  The functionality of the processor is analogous to the
 * ListClass doclet in the Doclet Overview.
 */
public class ListClassApf implements AnnotationProcessorFactory {
    // Process any set of annotations
    private static final Collection<String> supportedAnnotations
        = unmodifiableCollection(Arrays.asList("*"));

    // No supported options
    private static final Collection<String> supportedOptions = emptySet();

    public Collection<String> supportedAnnotationTypes() {
        return supportedAnnotations;
    }

    public Collection<String> supportedOptions() {
        return supportedOptions;
    }

    public AnnotationProcessor getProcessorFor(
            Set<AnnotationTypeDeclaration> atds,
            AnnotationProcessorEnvironment env) {
        return new ListClassAp(env);
    }

    private static class ListClassAp implements AnnotationProcessor {
        private final AnnotationProcessorEnvironment env;
        ListClassAp(AnnotationProcessorEnvironment env) {
            this.env = env;
        }

        public void process() {
	    for (TypeDeclaration typeDecl : env.getSpecifiedTypeDeclarations())
		typeDecl.accept(getDeclarationScanner(new ListClassVisitor(),
						      NO_OP));
        }

	private static class ListClassVisitor extends SimpleDeclarationVisitor {
	    public void visitClassDeclaration(ClassDeclaration d) {
		System.out.println(d.getQualifiedName());
	    }
	}
    }
}

The implementation of the AnnotationProcessorFactory defines the set annotations it can provide AnnotationProcessors for.
Also it provides the AnnotationProcessors to the framework.
The AnnotationProcessor itself is called by the framework by its process() method which does all the needed processing.

Run the APT Tool

apt -cp <ClassPath> -nocompile -s <Output> -factory <Factory> <SourceFiles>

Parameter	Description
-cp <ClassPath>	Path to the compiled class files.
-nocompile	No compilation of source files.
-s <Output>	Path to a directory where created files shall be placed.
-factory <Factory>	Fully qualified class path to your `AnnotationProcessorFactory`.
<SourceFiles>	The source files to be processeed.

Links

APT Tool Documentation
Example Impl. of AnnotationProcessorFactory

Operator Documentation

Automated Operator Documentation

Doclet API

Writing Doclets

Run a Doclet

Links

Annotation Processing Tool

Write an Annotation Processor

Run the APT Tool

Links

Labels