Javadoc bug: @link can't handle Generics “<>”

Question

Consider a static method in a class, which I have documented it using javadoc:

/**
 * Description here.
 *
 * @param names       - The parameters of the impression request.
 * @param ids         - An intent object to enrich.
 * @param prefix - A prefix.
 */

public static void parse(Map<String, String> names, String ids, String prefix)
    ...

In order to avoid duplicating the description in the overloaded versions of the method, I would like to use a javadoc @link:

 /**
 * Overloaded version with default prefix.
 * {@link #<parse(Map<String, String>, String, String)> [Text]}
 */

public static void parse(Map<String, String> names, String ids, String prefix)

Which gives the following warning:

@link:illegal character: "60" in "#parseBtCategories(Map<String, String>, 
                                                     String, String) Text"

ASCII 60 is <, which is a part of the method signature. It works with Map, String, String) nut this notation can't distinguish two different types of maps.

This seems to be a known bug. Is there a good workaround?

Answer 1

The parameterized types are NOT part of the method's signature.

Java implements Generics with Type Erasure. The concept of Type Erasure is that the generic types are only available at compile time, at which point they are "erased"; meaning they are stripped from the class's bytecode. Thus they are not accessible at runtime and are not part of method's signature.

So, there's no real reason for them to be part of the Javadoc link's signature, because you cannot overload two methods with generic types that resolve to the same raw types: there cannot be an ambiguity on the generic types in your source's signature.

Additionally, Javadoc supports HTML tags and I assume this could be another reason why it bites the dust here, but I really doubt the Javadoc processing tool was this badly implemented.

Answer 2

Similar to David Conrad solution, you can use the full signature as a link description, using syntax:

{@link class#method(signature) text-to-display}

Remember to escape < and >. For example:

 {@link #parse(Map, String, String) parse(Map<String, String>, String, String)}

Answer 3

It may not be what you're looking for, but I have learnt to live with something like * @return {@link List} of {@link RfRequestSummaryDto}