How do I make javadoc inheritance work for external APIs? (with Maven2)

Question

When a class overrides a concrete method or implements and abstract method, the Javadoc is automatically inherited unless explicitly overwritten.

Or, at least the tool tries to do this. It seems it does not work for linked external APIs. For instance, when I in my code implement java.util.Map, or something else from the JRE, the javadocs are not inherited/copied from the JRE javadocs/apidocs.

In my specific case, I am trying to configure this in the Maven2 Javadoc plugin, but it is the same when I run the javadoc CLI tool directly.

My Maven2 Javadoc plugin configuration currently looks like this:

<reporting>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>2.7</version>
      <configuration>
        <stylesheet>maven</stylesheet>
        <links>
          <link>http://download.oracle.com/javase/6/docs/api</link>
        </links>
      </configuration>
    </plugin>
  </plugins>
</reporting>

Any pointers on how to make this work?

Answer 1

As @Stephen mentioned, the source file for the inherited method must be available and must be on the path specified by -sourcepath. This is explained in the Javadoc tool documentation:

Automatic Copying of Method Comments

The Javadoc tool has the ability to copy or "inherit" method comments in classes and interfaces under the following two circumstances. Constructors, fields and nested classes do not inherit doc comments.

• Automatically inherit comment to fill in missing text - When a main description, or @return, @param or @throws tag is missing from a method comment, the Javadoc tool copies the corresponding main description or tag comment from the method it overrides or implements (if any), according to the algorithm below.

  More specifically, when a @param tag for a particular parameter is missing, then the comment for that parameter is copied from the method further up the inheritance hierarchy. When a @throws tag for a particular exception is missing, the @throws tag is copied only if that exception is declared.

  This behavior contrasts with version 1.3 and earlier, where the presence of any main description or tag would prevent all comments from being inherited.

• Explicitly inherit comment with {@inheritDoc} tag - Insert the inline tag {@inheritDoc} in a method main description or @return, @param or @throws tag comment -- the corresponding inherited main description or tag comment is copied into that spot.

The source file for the inherited method need only be on the path specified by -sourcepath for the doc comment to actually be available to copy. Neither the class nor its package needs to be passed in on the command line. This contrasts with 1.3.x and earlier releases, where the class had to be a documented class

So you'd have to use the <sourcepath> optional configuration parameter of the javadoc plugin (which contains by default the sources of the project).

---

By the way, <links/> are something else, <links/> are used to add cross reference links to external projects. And actually, they shouldn't be used for the JDK. From Configuring links:

Since 2.6, a Javadoc API link, depending the JDK version used by your project, will be added. The version of the Javadoc API is detected from the value of the <source/> parameter in the org.apache.maven.plugins:maven-compiler-plugin (defined in ${project.build.plugins} or in ${project.build.pluginManagement}), or computed via the Javadoc Tool executable. If you want to skip this link, you need to configure <detectJavaApiLink/> to false.

Note: if you are using an unsupported JDK like 7.0, you could add its Javadoc API url using the <javaApiLinks/> parameter, i.e.:

<configuration>
  <javaApiLinks>
    <property>
      <name>api_1.7</name>
      <value>http://download.java.net/jdk7/docs/api/</value>
    </property>
  </javaApiLinks>
  ...
</configuration>

Refer to <links/> parameter for more information.

Assuming you configured a 1.6 source level in the compiler plugin, cross references links to the Java API just works (links point to http://download.oracle.com/javase/6/docs/api/), there is nothing to add for the Java API.

---

Neither works out of the box for me. I had to add the links section to make the cross referencing work.

Weird. Did you actually specify the complier source level as documented? Just in case, here is what works for me:

  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
      <source>1.6</source>
      <target>1.6</target>
    </configuration>
  </plugin>
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.7</version>
    <configuration>
      <!-- No need for this -->
      <!--
      <javaApiLinks>
        <property>
          <name>api_1.6</name>
          <value>http://download.oracle.com/javase/6/docs/api/</value>
        </property>
      </javaApiLinks>
      -->
      <links>
        <link>http://commons.apache.org/dbcp/apidocs/</link>
        <link>http://commons.apache.org/fileupload/apidocs/</link>
      </links>
    </configuration>
  </plugin>

Answer 2

I cannot give you a definitive answer, but I think that the missing piece in the puzzle is that the javadoc utility needs to be able to find the source code of the relevant external APIs for javadoc inheritance to work.