Is there a way to produce Javadoc for a subset of public methods? For example by annotating public methods as “not part of the public API”

Question

I know how to produce Javadoc for a subset of classes/interfaces/packages. But is there a way to produce Javadoc for only a subset of public methods?

What I would prefer is to be able to mark methods (Javadoc tag or annotation) as belonging to a certain API or not be part of it. Then have a tool that produces Javadoc only for the specified set of methods - the ones which forms the API.

The choice between public/private/package access to a method is not enough for my project. A public method may belong to a public API or not, or it might belong to API 1, but not API 2. Essentially, I would like to be able to choose the API from an arbitrary subset of my public methods.

Answer 1

If you're using the javadoccommand line tool, you can exclude public methods by marking them as Deprecated and using the -nodeprecated option. But if you want something more sophisticated, you'll have to implement it yourself.

A rough idea on how to do it:

1. Create custom annotations @API1, @API2, etc.
2. Classify your methods with those annotations (i.e. mark them)
3. Write a custom Ant task which reads a configuration parameter (from a file, for example) that tells which API you want to generate the Javadoc for.
4. Still in the Ant task, Loop through the annotated methods and replace all API annotations which are NOT the selected API with the Deprecated annotation. This will exclude them from Javadoc.

IMHO, this is a lot of hassle. Like they said in the comments, if you have a class with multiple interfaces (for different user profiles, I guess?), consider writing separate interfaces.

Answer 2

If you are not tied to javadoc, you could alternatively try doxygen with conditional sections:

public class SomeClass {
    /// @cond API1
    /**
     * This method can be called as part of API1 only.
     */
    public void method() { ... }
    /// @endcond

    /// @cond (API1 || API2)
    /**
     * This method can be called as part of API1 or API2.
     */
    public void method2() { ... }
    /// @endcond
}

When you group the methods appropriately, you can also limit the number of required @cond statements.

The methods which are actually included can then be selected by the ENABLED_SECTIONS configuration option when creating the documentation.