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

Question

When a class overrides a particular method or implements an abstract method, Javadoc is automatically inherited if it is not explicitly overwritten.

Or at least the tool is trying to do this. This does not seem to work for related external APIs. For example, when I implement java.util.Map or something else from the JRE in my code, javadocs are not inherited / not copied from the JRE javadocs / apidocs.

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

The configuration of the Maven2 Javadoc plugin 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 accessible and must be in the path specified by -sourcepath . This is explained in the Javadoc tool documentation:

Automatically copy method comments

The Javadoc tool has the ability to copy or “inherit” the following two circumstances in the comments of the class and interface method. Constructors, fields, and nested classes do not inherit doc comments.

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

  More specifically, when the @param tag for a specific parameter is missing, then the comment for that parameter is copied from the hierarchy's further inheritance method. When the @throws tag for a specific exception is missing, the @throws tag is only copied if an exception is thrown.

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

• Explicitly inherit the comment with the tag {@inheritDoc} - insert the inline tag {@inheritDoc} into the description of the method or @return , @throws or @throws tag comment - the corresponding inherited main description or tag comment is copied to this place.

The source file for the inherited method should only be on the path specified by -sourcepath for the comment on the document actually available for copy. Neither the class nor its package should be on the command line. This contrasts with 1.3.x and earlier versions where the class was to be documented.

Thus, you will need to use the optional <sourcepath> javadoc configuration parameter (which by default contains project sources).

---

By the way, <links/> is something else, <links/> are used to add cross-references to external projects. And in fact, they should not be used for JDK. From link settings :

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

Note: if you are using an unsupported JDK, for example 7.0, you can add its Javadoc API URL using <javaApiLinks/> , <javaApiLinks/> .:

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

See <links/> details.

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

---

None of them are suitable for me. I had to add a link section to cross-reference.

Weird In fact, did you indicate the source compliance level as documented? Just in case, here's 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 a definitive answer, but I think the missing part in the puzzle is that the javadoc utility should be able to find the source code of the corresponding external APIs for Inheriting javadoc to work.

Answer 3

I had a similar question in StackOverflow that helped me solve this problem better than the accepted answer of this quest: maven-javadoc-plugin and inheritDoc for the main Java API classes

Summary: To inherit Javadoc from the core Java classes, you need to unzip their sources and include them in the Javadoc assembly. Sources for Java base classes are provided in the src.zip file in the JDK distribution.