Why won't Javadoc make my subclasses inherit documentation from Java's classes?

Question

I've been searching for an answer for several months and I have tried multiple things, including unzipping the Compressed folder src.zip and using it as a parameter for Javadoc (for example: javadoc -sourcepath src com.example.test)

This is the default Javadoc that comes with the JDK 6 Update 24.

Let's say that I'm working on a new map that implements the java.util.Map interface. By default the methods that I override from the Map interface should inherit the documentation from the interface, if I'm not mistaken. However, javadoc never does it.

The only thing that has worked this problem out so far, has been actually javadoc-ing the classes written by Java (for example: javadoc com.example.text java.util). I don't want to do this because it makes it seem like I rewrote the Java classes, but is this the only way to do it? If it is I suppose I could just live with it, but it was my understanding that there was another way to do this.

Thank you =) I'm sorry if this is a little messy. This is my first time using Stack Overflow. I'm also sorry if this question has been asked already. I have read many similar questions by they don't cover everything that I wanted to ask and I've found them very confusing because they involve writing your own implementation of Javadoc. Anyway, thank you in advanced =)

Edit: May 25 at 4:44

All right =) If I understand correctly, you would like to see an example. This is a simpler example that I tried to see if it was because I was trying something that shouldn't work.

package com.example;

/**
 * A simple class that returns an upper-case string representation.
 */
public class UpperCaseObject {

    @Override public int hashCode() {
        return super.hashcode();
    }

    /**
     * {@inheritDoc}
     *
     * <P>The {@code toString} method for class {@code UpperCaseObject} returns
     * converted to uppercase.</P>
     *
     * @see String#toUpperCase()
     */
    @Override public String toString() {
        return super.toString().toUpperCase();
    }

}

I moved this example (file name is UpperCaseObject.java) into a directory javadoc-test/com/example and I also made another directory javadoc-test/java/lang, placing Object.java (from src.zip) in it.

The call to javadoc that I made was javadoc -link http://download.oracle.com/javase/6/docs/api/ com.example from the directory javadoc-test. I have the jdk6 bin directory in my path parameter.

The two things that I expected was for UpperCaseObject.hashCode to inherit all of the documentation, and UpperCaseObject.toString everything before the extra paragraph from java.lang.Object. However, unfortunately, I didn't get any of the documentation.

Edit:

Well, what I had to do was the following. It is just a simple workaround.

1. I copied all the source files from source.zip like you would normally do so.
2. I also made package files for each package. They contain the very first paragraph (the one with the summary) and a second paragraph that says "See the Package Summary in the Java™ Platform, Standard Edition 6 API Specification for more information."
3. The source files were essentially the super classes, their super classes (and interfaces), and any exceptions that they threw that were also in the same package. The only exception was java.lang where I only needed to get Object. The exceptions were also needed because except for java.lang, the other packages did not link if an exception was in the same package as the throwing class.
4. I javadoc'd all the packages that I was using/subclassing/exception-throwing from.
5. I'll make sure to include some information about the standard packages and my own package in he overview file.

Unfortunately, I can only do a work around for now, but I'm convinced that it may be a problem with my version of Java. It sounds like other people have had a similar problem and came up with their own workarounds. This is just my own =)

I'll still be taking answers, but this is the most convenient option in the meanwhile. Thank you very much!

Answer 1

One thing you can do is link to the official Javadoc for those classes, using the -link option:

javadoc -sourcepath src -link http://download.oracle.com/javase/6/docs/api com.example.test

This will allow Javadoc to treat the classes of the SDK as "external referenced classes". From the Javadoc documentation:

The referenced classes whose documentation is not being generated during a javadoc run. In other words, these classes are not passed into the Javadoc tool on the command line. Links in the generated documentation to those classes are said to be external references or external links. For example, if you run the Javadoc tool on only the java.awt package, then any class in java.lang, such as Object, is an external referenced class. External referenced classes can be linked to using the -link and -linkoffline options. An important property of an external referenced class is that its source comments are normally not available to the Javadoc run. In this case, these comments cannot be inherited.

Note that the Javadoc for these class will still not be inherited. However, you can now link to it, like so:

public class MyMap implements java.util.Map {
    ...
    /**
     * @see java.util.Map#isEmpty()
     */
    @Override
    public boolean isEmpty() {
        ...
    }
}

[EDIT]

The @see tag is there for illustration. Javadoc should automatically generate a "Specified By" link, so you could omit the Javadoc comment altogether.

Answer 2

The source file for the inherited method needs to be on the -sourcepath of the javadoc tool when it runs. You don't need to pass the inherited class on the command line.