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

Question

I searched for the answer for several months and I tried several things, including unpacking the compressed src.zip folder and using it as a parameter for Javadoc (for example: javadoc -sourcepath src com.example.test )

This is the default Javadoc that ships 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 this.

The only thing so far working on this problem was actually javadoc-ing classes written by Java (for example: javadoc com.example.text java.util ). I do not want to do this because it seems to me that I have rewritten Java classes, but is this the only way to do this? If I believe that I could just live with him, but I realized that there is another way to do this.

Thanks =) Sorry if this is a little dirty. This is my first time using Stack Overflow. I'm also sorry if this question has already been asked. I read a lot of similar questions, they do not cover everything that I wanted to ask, and I found them very confusing because they are related to writing my own implementation of Javadoc. Anyway, thank you in advanced =)

Edit: May 25 at 4:44 am

Everything is correct =) If I understood correctly, you would like to see an example. This is a simpler example that I tried to see if it was because I tried something that should not 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 UpperCaseObject.java ) to the javadoc-test/com/example directory, and also created another javadoc-test/java/lang directory by placing Object.java (from src.zip) in it.

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

The two things I expected were for UpperCaseObject.hashCode to inherit all the documentation and UpperCaseObject.toString all the way up to the extra paragraph from java.lang.Object . However, unfortunately, I did not receive any documentation.

Edit:

Well, I needed to do the following. This is an easy workaround.

• I copied all the source files from source.zip, as you usually did.
• I also made package files for each package. They contain the first paragraph (the one that contains the resume) and the second paragraph that says: "See the " Package Summary "in the Java ™ Edition 6 API for more information."
• The source files were, in fact, superclasses, their superclasses (and interfaces), and any exceptions that they threw, which were also in the same package. The one exception was java.lang, where I only needed to get an Object. Exceptions were also needed because, apart from java.lang, no other packages were bound if the exception was in the same package as the throwing class.
• I javadoc'd all the packages that I used / subclassing / exception -throwing.
• I will definitely include some information about standard packages and my own package in its overview file.

Unfortunately, now I can only work, but I am convinced that this may be a problem with my version of Java. It seems that other people had a similar problem and they came up with their workarounds. This is just my own =)

I will still answer, but this is the most convenient option. Thank you very much!

Answer 1

The source file for the inherited method must be on the -sourcepath of the javadoc tool when it runs. You do not need to pass an inherited class on the command line.

Answer 2

One thing you can do is reference the official Javadoc for these classes using the -link :

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

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

Associated classes whose documentation is not generated when javadoc starts. In other words, these classes are not passed to the Javadoc tool on the command line. References in the generated documentation to these classes are called external links or external links. For example, if you run the Javadoc tool only for the java.awt package, then any class in java.lang, such as Object, is an external reference class. External reference classes can be linked using the -link and -linkoffline options. An important property of an external reference class is that its original comments are usually not available to run Javadoc. In this case, these comments cannot be inherited.

Note that the Javadoc for this class will still not be inherited. However, now you can refer to it as follows:

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

[EDIT]

The @see tag is shown for illustration. Javadoc should automatically generate a "Specified by" link, so you can skip the Javadoc comment altogether.