Menu
I am writing my own Java 8 Stream implementation and want to inherit the Javadocs from the original java.util.stream.Stream interface. However I cannot get it working. The generated Javadoc does only show my documentation but not the documentation from the extended Stream interface.
So for example, the javadoc of this method does only contain the text "Some additional information" but not the documentation from the Stream interface.
/**
* {@inheritDoc}
* Some additional information.
*/
@Override
public Stream<T> filter(Predicate<? super T> predicate) {
// ... my stream implementation...
}
This is my configuration of the maven-javadoc-plugin:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.10.1</version>
<configuration>
<links>
<link>http://docs.oracle.com/javase/8/docs/api/</link>
</links>
</configuration>
</plugin>
Do I miss something in this configuration? I set source and target to 1.8 in the maven-compiler-plugin. So according to the documentation of the maven-javadoc-plugin, the java API should be detected automatically.
There was also a similar question on Stack Overflow but the answers there do not seem helpful.
616
That is expected, javadoc only copies comments from classes that are inside the source path. From Method Comment Inheritance:
Note: The source file for an inherited method must be on the path specified by the
-sourcepathoption for the documentation comment to be available to copy. Neither the class nor its package needs to be passed in on the command line. This contrasts with Release 1.3.n and earlier releases, where the class had to be a documented class.
However, the sources of your JDK aren't in the source path, so {@inheritDoc} won't copy it. They need to be added explicitely; the Javadoc FAQ has this entry:
Inheriting Comments from J2SE - Your code can also automatically inherit comments from interfaces and classes in the J2SE. You can do this by unzipping the
src.zipfile that ships with the SDK (it does not contain all source files, however), and add its path to-sourcepath. Whenjavadocruns on your code, it will load the doc comments from those source files as needed. For example, if a class in your code implementsjava.lang.Comparable, thecompareTo(Object)method you implement will inherit the doc comment fromjava.lang.Comparable.
So, to make it work:
maven-javadoc-plugin to add those sources with the sourcepath parameter.subpackages to specify only our packages. Alternatively, we can use excludePackageNames to exclude the JDK packages.@apiNote, @implSpec and @implNote. Those are custom tags that need to be added with the tags parameter.Here's a sample configuration, where the path to the JDK sources is /path/to/jdk/sources (you could also use an environment variable, a property set by profile, etc.) and your own source files are all in the package my.package:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.10.1</version>
<configuration>
<sourcepath>/path/to/jdk/sources:${basedir}/src/main/java</sourcepath>
<subpackages>my.package</subpackages>
<tags>
<tag>
<name>apiNote</name>
<placement>a</placement>
<head>API Note:</head>
</tag>
<tag>
<name>implSpec</name>
<placement>a</placement>
<head>Implementation Requirements:</head>
</tag>
<tag>
<name>implNote</name>
<placement>a</placement>
<head>Implementation Note:</head>
</tag>
</tags>
</configuration>
</plugin>
Generating the Javadoc, for example with mvn javadoc:javadoc, will correctly resolve the {@inheritDoc}.
179
Tunaki's answer is great but as of Java 10 you have an even better option. If you pass --override-methods=summary to the Javadoc tool it'll push all inherited methods down to a "Methods declared in class X" section down below. This will list the inherited methods. Clicking on method names will take the user to the Javadoc definition in the base class.
See https://bugs.java.com/bugdatabase/view_bug.do?bug_id=8187386 for background information.
27
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
