Inherit javadoc, without generating docs for inher

Question

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?

Answer 1

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.

---

So thought I'd share what I went with for anyone managing their project with maven and using maven-javadoc-plugin as part of their build process to generate their docs.

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>

---

Btw, if you found anything on this page useful, please link to it somewhere. Finding this page on google was too difficult and this is a really nice thing to have.

Answer 2

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,
• my own sources are in src,
• the sources for interface A are in ../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 :-)