FULL PRODUCT VERSION :
java version "1.5.0_06"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_06-b05)
Java HotSpot(TM) Client VM (build 1.5.0_06-b05, mixed mode, sharing)

ADDITIONAL OS VERSION INFORMATION :
Microsoft Windows XP [Version 5.1.2600]

A DESCRIPTION OF THE PROBLEM :
First, note that I only filed this bug report after enagaging in this discussion on the java forums:
http://forum.java.sun.com/thread.jspa?threadID=698169&tstart=0

To repeat the forum discussion above, here is the issue:

If you create @link or @see javadoc tags that reference a method which takes parameter(s), then javadoc creates an html link in which the text for the parameter(s) is the type of the parameter (which is good), but the type is listed in fully qualified format (which is bad).

What makes this a bug is that javadoc uses this fully qualified form even if you have used the -link option to correctly link to the javadocs for the parameter's type.

It also is a bug because if you specify the noqualifier option to javadoc (e.g. noqualifier all), it still uses a fully qualified format for the parameter's text in the link, contrary to what the noqualifier option would you expect you to get.

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
Here is a worked example proving this as a bug.

Consider this source file:

[code]
//package ...;

import java.awt.Graphics2D;

/**
* This class defines just a single method: {@link #arbitraryMethod}.
* @see #arbitraryMethod
*/
public class JavadocBug {

public static void arbitraryMethod(Graphics2D g2) {}

}
[/code]

Obviously, place it in a file named JavadocBug.java and compile it via
javac JavadocBug.java

Then execute the MSDOS bat file below (or do the equivalent in some unix shell script or whatever), uncommenting whatever setting you want for the noqualifier env var, and see that it makes no difference.


[code]
::--------------------------------------------------
:: MSDOS Bat file which makes javadocs for all the classes in this project.
::
:: The actions performed are:
:: 1) define some environmental variables used in this bat file
:: 2) generate javadocs for all these packages (i.e the ones listed in javaPackages.txt); execution will terminate if an error is detected
::
:: The current version of this file works under the JDK 1.5.0 javadoc tool,
:: altho it should only take a few minor tweaks (modify/remove a few options)
:: to get it work with older javadoc versions.
::
:: Side effect: echo will be off when this bat file finishes.
::--------------------------------------------------
::
::
@echo off


::----------step 1): define environment variables

set javadocDir=.\javadoc

set jdkVersion=-source 1.5

set links=%links% -link http://java.sun.com/j2se/1.5.0/docs/api/

set noqualifier=
::set noqualifier=-noqualifier all
::set noqualifier=-noqualifier java.awt

set outputLevel=-verbose

set private=-private

set prompt=%promptNone%


::----------step 2): generate javadocs

echo.
echo on
::
::
javadoc -breakiterator -classpath .\ -d %javadocDir% %jdkVersion% %links% %noqualifier% %outputLevel% %private% -serialwarn -sourcepath .\ -use JavadocBug.java
@if errorlevel 1 goto handleError
::
@echo off


::----------error handling and final actions:

:handleError
@echo off
if not errorlevel 1 goto finalActions
echo.
echo ERROR DETECTED: jd.bat will TERMINATE PREMATURELY

:finalActions
@echo off
set prompt=%promptOriginal%
[/code]


EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
In the code example given in "Steps to Reproduce:" above, I would have expected the @link and @see links to have the text
arbitraryMethod(Graphics2D)

The above, by the way, is essentially how it DOES appear if you look at the javadocs for the arbitraryMethod method itself (except that it adds the param name too, and the Graphics2D part is itself a hyperlink to the javadocs for Graphics2D).

ACTUAL -
Instead of the desired text, the @link and @see tags have the following fully qualified type name form for the parameter:
arbitraryMethod(java.awt.Graphics2D)

As noted above, you get this fully qualified param name form even if you have correctly linked to the external javadocs for Graphics2D (as proved by how the javadocs for the arbitraryMethod itself behave properly), as well as if you use the noqualifier option.

REPRODUCIBILITY :
This bug can be reproduced always.

CUSTOMER SUBMITTED WORKAROUND :
You can awkwardly specify the param type explicitly in your @link and @see tags.

For the example given above, this means that you can use
    {@XXX #arbitraryMethod(Graphics2D)}
instead of just
    {@XXX #arbitraryMethod}
where @XXX is @link or @see. This causes the correct behavior.

You can also do the even more tedious form of using a label, like
    {@XXX #arbitraryMethod arbitraryMethod(Graphics2D)}

However, I should not have to do either of these. As Doug Kramer on that forum discussion points out, your own documents say that the simple #arbitraryMethod form should be sufficient:

"If any method or constructor is entered as a name with no parentheses, such as getValue, and if there is no field with the same name, the Javadoc tool will correctly create a link to it, but will print a warning message reminding you to add the parentheses and arguments. If this method is overloaded, the Javadoc tool will link to the first method its search encounters, which is unspecified."
http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#typicalformsfor@see