I would like class B to inherit the Javadoc from an interface that it implements, interface A. I have included the source for interface A in my Javadoc command, and class B correctly inherits the documentation.
Now I'm wondering if I can make the links it generates point to interface A's documentation on the web, rather than duplicating it on my site, i.e. the "Specified by:" links will link to an external page.
Is this possible?
It is possible, yes.
For being able to include inherited documentation, the source of interface A has to be findable in the sourcepath of javadoc, but should not be in the list of packages passed to javadoc for documentation creation.
For linking, use the -link parameter. I just tried this (with the ant javadoc task):
<javadoc destdir="docs">
<sourcepath>
<!-- source of your class B -->
<pathelement location="src" />
<!-- source of external interface A -->
<pathelement location="../example-src/src" />
</sourcepath>
<!-- your packages, to generate the docs for -->
<package name="com.personal.myproject.*" />
<!-- the location of the online documentation -->
<link href="http://example.com/javadoc/"/>
</javadoc>
To command line javadoc, I think this translates like this (unix syntax, one line):
javadoc -sourcepath ../example-src/src:src
-d docs
-link http://example.com/javadoc/
-subpackages com.personal.myproject
(other options...)
where
class B is in package com.personal.myproject,interface A is in package com.example,src,../example-src/src.In a example class created for this, javadoc would copy the documentation from A.methodName() to B.methodName(), but link to the online documentation at http://example.com/javadoc/com/example/A.html#methodName().
Thanks for asking this question, I always wanted to do this :-)
Huge credit to Paŭlo Ebermann's answer for pointing me in the right direction for my set up. Please read that answer first as it makes sense of this while I am just providing an additional way to configure the solution.
As part of the plugin's configuration you can specify a group of links to include. Here is the bit that specifically covers configuring links.
And here is a sample linking external documentation for selenium and java se for packaging in a jar to deploy with my project. The beauty is that these javadocs in my project just link out to the external ones seemlessly.
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
<configuration>
<links>
<link>http://seleniumhq.github.io/selenium/docs/api/java/</link>
<link>https://docs.oracle.com/javase/${project.java.version}/docs/api/</link>
</links>
</configuration>
</plugin>
