Javadoc bug：@link无法处理泛型“<>” [英] Javadoc bug: @link can't handle Generics "<>"

问题描述

考虑一个类中的静态方法，我使用 javadoc 来记录它：

/ **
*
*
* @param名称 - 展示请求的参数。
* @param ids - 一个用于丰富的意图对象。
* @param prefix - 一个前缀。
* /

public static void parse（Map< String，String> names，String id，String prefix）
...
@link $ b>

/ code>：

/ **
*字首。
* {@link＃< parse（Map< String，String>，String，String）> [Text]}
* /

public static void parse（Map< String，String> names，String id，String prefix）
pre>

给出以下警告：

  @link：非法字符：#parseBtCategories（Map< String，String> ;, 
 String，String）中的60文本
  

ASCII 60是< ，它是方法签名的一部分。它适用于 Map，String，String）这个记法无法区分两种不同类型的地图。

这似乎是一个已知的错误。有没有很好的解决方法？ / b>

解决方案

参数化类型不是方法签名的一部分。

Java通过 泛型实现泛型。 http://docs.oracle.com/javase/tutorial/java/generics/erasure.html\">类型擦除 。类型擦除的概念是泛型类型仅在编译时可用，此时它们被擦除;这意味着它们从类的字节码中剥离出来。因此，它们在运行时不可访问，不是方法签名的一部分。

因此，没有真正的原因因为它们是Javadoc链接签名的一部分，因为不能使用解析为相同原始类型的泛型类型重载两个方法：源代码签名中的泛型类型不能有歧义。 / p>

另外，Javadoc支持HTML标签，我认为这可能是其中一个原因，因为它在这里咬了灰尘，但我真的怀疑Javadoc处理工具是否实施得很糟糕。

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?

解决方案

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.

这篇关于Javadoc bug：@link无法处理泛型“&lt;&gt;”的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！