Maven javadoc plugin - how can I include only certain classes?

Question

Using the Maven javadoc plugin you can exclude certain packages - but I have lots of packages and only a handful of classes I want to produce Javadoc for.

Is there a way to include rather than exclude?

I would also like to do things on a class level rather than a package level as I have some classes in a package which need javadoc and some which don't.

Answer 1

As far as I know you can only filter at the package level. However Javadoc is only generated for public and protected types. If the types are default-scoped or private they won't have javadoc generated for them. Making them default-scoped means they are still visible to other types in the package.If you don't want javadoc, you probably don't want people to use those types, so this is probably a good scope to go for anyway.

The excludePackageNames configuration allows wildcards. So as long as you have a package name convention that allows this you can exclude the majority of packages.

Say you have these packages.

com.foo
com.foo.api
com.foo.internal   
com.foo.internal.core
com.foo.internal.util
com.foo.internal.ui
com.foo.ui

and you only want to expose foo, foo.api and foo.ui, this pattern will work:

<excludePackageNames>com.foo.internal.*:com.foo.bob</excludePackageNames>

You could alternatively move the offending types into separate packages, but this is not a good reason to do so.

What is the issue with generating javadoc for these types?

Answer 2

Using the maven-javadoc-plugin, you cannot specify specific java classess (though you can with the javadoc utility, see below). However, via the the sourcepath configuration option for the javadoc:javadoc goal, you can configure specific packages. An example of this follows:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.5</version>
    <configuration>
        <charset>UTF-8</charset>
        <docencoding>UTF-8</docencoding>
        <docfilessubdirs>true</docfilessubdirs>
        <links>
            <link>http://java.sun.com/j2se/1.5.0/docs/api/&lt;/link&gt;
        </links>
        <show>protected</show>
        <source>1.5</source>
        <sourcepath>${basedir}/src/main/java/com/acme/foo</sourcepath>
    </configuration>
    <reportSets>
        <reportSet>
            <reports>
                <report>javadoc</report>
            </reports>
        </reportSet>
    </reportSets>
</plugin>

In this example, all classes under the com.acme.foo package (including subpackages) will have javadoc generated.

It should be noted that this Maven plugin is simply a wrapper around Sun's javadoc utility. As such, most of the documentation and configuration for javadoc holds true for this plugin. See Sun's documentation on the javadoc sourcepath parameter.

In an area where the maven-javadoc-plugin differs in functionality, Sun's documentation for the sourcepath parameter mentions that it is possible with the javadoc utility to generate javadoc for specific classes. This capability is not available with the maven-javadoc-plugin. An example of this is shown in Sun's documentation:

  C:> cd C:\home\src\java\awt
  C:> javadoc -d C:\home\html Button.java Canvas.java Graphics*.java

Answer 3

In the end I used the sourcepath configuration option to specify two packages containing the classes I wanted to Javadoc and gave classes in those packages that I didn't want to Javadoc default access. Setting the show configuration option to public allowed me to choose which classes Javadoc was produced for by setting there access to public. Full configuration below:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
     <links>
      <link>http://java.sun.com/j2se/1.5.0/docs/api/&lt;/link&gt;
     </links>
     <source>1.5</source>
     <show>public</show>
     <doctitle>Foo API</doctitle>
     <title>Foo API</title>
     <bottom><![CDATA[Copyright notice]]></bottom>
     <sourcepath>${basedir}/src/main/java/com/foo/api;${basedir}/src/main/java/com/bar/api</sourcepath>
    </configuration>
</plugin>

However, this is essentially a workaround and I strongly agree with shek's comment that this should be an enchancement against the maven-javadoc-plugin as it is supported by the javadoc utility. http://jira.codehaus.org/browse/MJAVADOC

Answer 4

It's simply, when you use the configuration tag <subpackages/> from Maven2-Plugin, e.g.:

    <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.7</version>
    <configuration>
        <sourceEncoding>ISO-8859-1</sourceEncoding>
        <quiet>true</quiet>
        <aggregate>true</aggregate>
        <code>javadoc:aggregate</code>
        <code>javadoc:test-aggregate</code>         
        <doclet>gr.spinellis.umlgraph.doclet.UmlGraphDoc</doclet>
        <docletArtifact>
            <groupId>gr.spinellis</groupId>
            <artifactId>UmlGraph</artifactId>
            <version>4.6</version>
        </docletArtifact>
        <additionalparam>
            -inferrel -inferdep -quiet -hide java.*
            -collpackages java.util.* -qualify
            -postfixpackage -nodefontsize 9
            -nodefontpackagesize 7                          
        </additionalparam>

        <subpackages>
            de.interforum.gms.db.domain:de.interforum.sdr.db.domain
        </subpackages>

    </configuration>
    <executions>
      <execution>
        <goals>
          <goal>javadoc</goal>
          <goal>test-javadoc</goal>
        </goals>
        <phase>site</phase>
        <configuration>
          <!-- Specific configuration for the given reports ... -->
        </configuration>
      </execution>
    </executions>
</plugin>