Javadoc 1.4 Beta 2 - Possible Bug with @see
I'm currently using javadoc 1.3 to generate some documentation. It runs fine, no errors or warnings.
When I run Javadoc 1.4 Beta 2 using the same parameters and source files I get three warnings generated by three similar @see tags:
warning - Tag @see: Class or Package not found: Throwable#printStackTrace
warning - Tag @see: Class or Package not found: java.lang.Throwable#printStackTrace(java.io.PrintStream)
warning - Tag @see: Class or Package not found: java.lang.Throwable#printStackTrace(java.io.PrintWriter)
The api javadoc is on my c: drive.
Any ideas?
Vince.
PS. Here's my javadoc parameters file contents:
-d p:\java\javadoc -link c:\progra~1\jbuild~2\docs\api -sourcepath p:\java com.vincentosullivan.tools com.vincentosullivan.tools.test
Do all other links to java.lang actually work when you click on them?Would you mind pasting in the doc comments that cause these warnings?Also please paste in the import statement from that source file.-Doug KramerJavadoc team
> Do all other links to java.lang actually work when you
> click on them?
@see Exception
works with both Javadoc 1.3 and 1.4.
@see Throwable#printStackTrace
works with Javadoc 1.3 but throws warnings with 1.4.
Where the links have been created, they work.
> Would you mind pasting in the doc comments that cause
> these warnings?
Here's an example (it is based on article about Chained Exceptions at http://www.javaworld.com/javaworld/jw-09-2001/jw-0914-exceptions.html?):
public class ChainedException
extends Exception
{
/** The exception/error that is to be 'chained' onto this one. */
private Throwable cause = null;
/**
* CONSTRUCTOR: Defers to the <code>Exception(String)</code> constructor
* but additionally stores the exception that led to this one being thrown.
*
* @param message A meaningful error message.
* @param causeThe original exception that led to this one being thrown.
* @see java.lang.Exception
*/
public ChainedException(String message, Throwable cause)
{
super(message);
this.cause = cause;
}
/**
* Prints this <code>Throwable</code> (and its backtrace) to the standard error stream.
*
* @see Throwable#printStackTrace
*/
public void printStackTrace()
{
super.printStackTrace();
if (cause != null)
{
System.err.println("Caused by:");
cause.printStackTrace();
}
}
}
}
> Also please paste in the import statement from that
> source file.
There are no import statements in the source file.
I've just tried adding import java.lang.Throwable;
to the source and running both versions of Javadoc. It made no difference to the results.
Vince
Thanks for the information.
Javadoc was reimplemented in 1.4 to handle assertions,
and in doing so, some side effects may have occurred.
Would you please try a stricter argument for @see:
@see Throwable#printStackTrace(PrintStream)
BTW, on an unrelated question,
do your doc comments actually have a left
angle bracket at the start of each "code" HTML tag
and an ampersand-g-t-semicolon following it, as
I happen to see in your pasted text?
-Doug Kramer
Javadoc team
> Thanks for the information.
>
> Would you please try a stricter argument for @see:
>
> @see Throwable#printStackTrace(PrintStream)
The original code overrode all the printStackTrace variants and had the appropriate @see references. I just posted a simplified version. It made no difference though. They all work with 1.3 but none with 1.4.
Tried it with and without import statements in the file and with and without package qualifiers (e.g.@see java.lang.Throwable#printStackTrace(PrintStream)
in the comments. None of the alterations made any difference to the outcome. @see Throwable variants always worked with 1.3 and not 1.4. @see Exception variants worked with both versions.
>
> BTW, on an unrelated question,
> do your doc comments actually have a left
> angle bracket at the start of each "code" HTML tag
> and an ampersand-g-t-semicolon following it, as
> I happen to see in your pasted text?
I noticed that too. I assumed it was an artifact of the web page since my source code uses the "<" and ">" characters, as you would expect and not escape sequences.
Incidentally the -subpackages parameter seems to work fine.
Vince.
I can reproduce the problem here at Sun. It appears that in 1.4,
all @see links to external referenced members (using -link) are not
created -- the text appears but there is no link.
If you send your email address to javadoc-tool@sun.com,
I can put you on the interest list for this bug.
I'll try to get it fixed for the final release.
Thank you very much for pointing this out.
-Doug Kramer
