Name: rmT116609 Date: 09/02/2004


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

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

A DESCRIPTION OF THE PROBLEM :
When trying use the @see and @link tags with methods that have Generics for parameters, such as printLocales(ArrayList<Locale>), errors are produced and no link is made. The '<' and '>' characters are reported as illegal. If you try and use the html equivalents '&lt;' and '&gt;' you get errors indicating that both the '&' and ';' are also illegal characters.

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
Given the following code snipplet, run the javadoc utility on it:

import java.util.ArrayList;
import java.util.Locale;

public class Test {

  /**
   * Used to output the <code>Locale</code> objects stored in an <pre>ArrayList<Locale></pre> object
   */
  public static void printLocales(ArrayList<Locale> locales) {
    System.out.println(locales.toString());
  }

  /**
   * Used to output a single Locale
   */
  public static void printLocales(Locale locale) {
    System.out.println(locale.toString());
  }

  /**
   * Uses the {@link #printLocales(Locale)} and {@link #printLocales(ArrayList<Locale>)} methods
   * to display the <code>Locale</code> objects
   * @see #printLocales(Locale)
   * @see #printLocales(ArrayList<Locale>)
   */
  public static void main(String[] args) {
    ArrayList<Locale> locales = new ArrayList<Locale>();
    locales.add(Locale.US);
    locales.add(Locale.GERMANY);
    printLocales(locales);
    printLocales(Locale.US);
  }
}

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
The error produced by the lines:
   * Uses the {@link #printLocales(Locale)} and {@link #printLocales(ArrayList<Locale>)} methods
   * @see #printLocales(ArrayList<Locale>)
Should have produced a valid link. In the generated Javadoc, the name reference is:
<A NAME="printLocales(java.util.ArrayList)">
This should have been something to reference the fact that the java.util.ArrayList is a generic type such as:
<A NAME="printLocales(java.util.ArrayList<Locales>)">
Given the problem with how the < and > character are interpreted in html however I'm not sure what the best solution would be. Maybe use the &lt; and &gt; instead.
ACTUAL -
No link is produced by the Javadoc tag @link or @see, only a <CODE>#printLocales(ArrayList&lt;Locale&gt;)</CODE> section is generated for the See Also: section, no actual link the the appropriate block of code.

ERROR MESSAGES/STACK TRACES THAT OCCUR :
E:\Test>javadoc Test.java
Loading source file Test.java...
Constructing Javadoc information...
Standard Doclet version 1.5.0-rc
Building tree for all the packages and classes...
Generating Test.html...
Test.java:26: warning - Tag @see:illegal character: "60" in "#printLocales(ArrayList<Locale>)"
Test.java:26: warning - Tag @see:illegal character: "62" in "#printLocales(ArrayList<Locale>)"
Test.java:26: warning - Tag @see: can't find printLocales(ArrayList<Locale>) in Test
Test.java:26: warning - Tag @link:illegal character: "60" in "#printLocales(ArrayList<Locale>)"
Test.java:26: warning - Tag @link:illegal character: "62" in "#printLocales(ArrayList<Locale>)"
Test.java:26: warning - Tag @link: can't find printLocales(ArrayList<Locale>) in Test
Generating package-frame.html...
Generating package-summary.html...
Generating package-tree.html...
Generating constant-values.html...
Building index for all the packages and classes...
Generating overview-tree.html...
Generating index-all.html...
Generating deprecated-list.html...
Building index for all classes...
Generating allclasses-frame.html...
Generating allclasses-noframe.html...
Generating index.html...
Generating help-doc.html...
Generating stylesheet.css...
6 warnings

-----------------------

Changing the offending line to:
   * Uses the {@link #printLocales(Locale)} and {@link #printLocales(ArrayList&lt;Locale&gt;)} methods
   * @see #printLocales(ArrayList&lt;Locale&gt;)
Produces this output:

-----------------------

E:\Test>javadoc Test.java
Loading source file Test.java...
Constructing Javadoc information...
Standard Doclet version 1.5.0-rc
Building tree for all the packages and classes...
Generating Test.html...
Test.java:26: warning - Tag @see:illegal character: "38" in "#printLocales(ArrayList&lt;Locale&gt;)"
Test.java:26: warning - Tag @see:illegal character: "59" in "#printLocales(ArrayList&lt;Locale&gt;)"
Test.java:26: warning - Tag @see:illegal character: "38" in "#printLocales(ArrayList&lt;Locale&gt;)"
Test.java:26: warning - Tag @see:illegal character: "59" in "#printLocales(ArrayList&lt;Locale&gt;)"
Test.java:26: warning - Tag @see: can't find printLocales(ArrayList&lt;Locale&gt;) in Test
Test.java:26: warning - Tag @link:illegal character: "38" in "#printLocales(ArrayList&lt;Locale&gt;)"
Test.java:26: warning - Tag @link:illegal character: "59" in "#printLocales(ArrayList&lt;Locale&gt;)"
Test.java:26: warning - Tag @link:illegal character: "38" in "#printLocales(ArrayList&lt;Locale&gt;)"
Test.java:26: warning - Tag @link:illegal character: "59" in "#printLocales(ArrayList&lt;Locale&gt;)"
Test.java:26: warning - Tag @link: can't find printLocales(ArrayList&lt;Locale&gt;) in Test
Generating package-frame.html...
Generating package-summary.html...
Generating package-tree.html...
Generating constant-values.html...
Building index for all the packages and classes...
Generating overview-tree.html...
Generating index-all.html...
Generating deprecated-list.html...
Building index for all classes...
Generating allclasses-frame.html...
Generating allclasses-noframe.html...
Generating index.html...
Generating help-doc.html...
Generating stylesheet.css...
10 warnings

-----------------------

REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
import java.util.ArrayList;
import java.util.Locale;

public class Test {

  /**
   * Used to output the <code>Locale</code> objects stored in an <pre>ArrayList<Locale></pre> object
   */
  public static void printLocales(ArrayList<Locale> locales) {
    System.out.println(locales.toString());
  }

  /**
   * Used to output a single Locale
   */
  public static void printLocales(Locale locale) {
    System.out.println(locale.toString());
  }

  /**
   * Uses the {@link #printLocales(Locale)} and {@link #printLocales(ArrayList<Locale>)} methods
   * to display the <code>Locale</code> objects
   * @see #printLocales(Locale)
   * @see #printLocales(ArrayList<Locale>)
   */
  public static void main(String[] args) {
    ArrayList<Locale> locales = new ArrayList<Locale>();
    locales.add(Locale.US);
    locales.add(Locale.GERMANY);
    printLocales(locales);
    printLocales(Locale.US);
  }
}
---------- END SOURCE ----------

CUSTOMER SUBMITTED WORKAROUND :
do not use generics when referencing methods with generics, just use the collection type instead.
(Incident Review ID: 301704)
======================================================================