Name: rmT116609 Date: 04/28/2003


DESCRIPTION OF THE REQUEST :

Please take a look at:
http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#inheritingcomments

Note the sentence that reads, "The overridden method must be a member of a documented class, and not an external referenced class for the doc comment to actually be available to copy."

I guess the reason for this is that in order to inherit the comments you need the source code for the overridden methods, right? Okay, that makes sense to me.

What I don't understand is why the "Specified by:" and "Overrides:" links are put in the same category as inherited comments.

In other words, It seems to me that if I have either source files *or* class files for my superclasses/interfaces, then it should be possible for the javadoc tool to generate the "Specified by:" and "Overrides:" links, regardless of whether or not I'm able to inherit method comments, but this is not how the tool behaves.

Here's an example: I have a class called XReader that extends java.io.FilterReader. When I run javadoc on XReader, I specify the "-link" option, pointing to "http://java.sun.com/j2se/1.4.2/docs/api". Of course, my XReader docs do not inherit any docs for the Reader methods I override. This makes sense to me.

But, since I *do* have the class files for everything in java.io.*, it seems the javadoc tool should be able to provide the "Specified by:" and "Overrides:" links in my XReader docs.

The only time I can see when it would be impossible to generate "Specified by:" or "Overrides:" links is when the source code *AND* class files for the classes/interfaces whose methods are being overridden/implemented are not available. Whether or not these classes/interfaces are "external referenced classes" seems irrelevant.

I guess to sum it up, it seems that the generation of "Specified by:" or "Overrides:" links is really independent of whether or not it's possible to inheriting comments yet the javadoc tool seems to put them together.

JUSTIFICATION :
It would basically expand the usefulness of the "Specified by:" and "Overrides:" links. Currently, these links are generated only when you generate javadoc for the superclasses/interfaces you are extending/implementing along with your class.

These links could (and I think, should) be generated even if you are not generating docs for the superclasses/interfaces but only generating the docs for your classes.

In my description I give an example of a class XReader that extends FilterReader. For XReader to have the "Specified by:" and "Overrides:" links I need to generate javadocs for java.io.Reader too, otherwise, I don't get the links.
(Review ID: 184931)
======================================================================