Javadoc 错误：@link 无法处理泛型“<>”答案

【问题标题】：Javadoc bug: @link can't handle Generics "<>"Javadoc 错误：@link 无法处理泛型“<>”
【发布时间】：2012-03-17 22:43:04
【问题描述】：

考虑一个类中的静态方法，我使用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)
    ...

为了避免在方法的重载版本中重复描述，我想使用一个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)

给出以下警告：

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

ASCII 60 是<，它是方法签名的一部分。它适用于Map, String, String) nut，这种表示法无法区分两种不同类型的地图。

This seems to be a known bug.有什么好的解决方法吗？

【问题讨论】：

只是为了确保：您是否真的在 < 之前使用 {@link#<parse 和 parse 之前的 <？这是最近添加的新语法吗？

标签： generics javadoc

【解决方案1】：

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

Java 使用 Type Erasure 实现 Generics。 concept of Type Erasure 是 generic types 仅在编译时可用，此时它们被“擦除”；意味着它们被从类的字节码中剥离。因此它们在运行时无法访问并且不是方法签名的一部分。

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

此外，Javadoc 支持 HTML 标记，我认为这可能是它在这里尘埃落定的另一个原因，但我真的怀疑 Javadoc 处理工具的实现是否如此糟糕。

【讨论】：

我认为这个论点站不住脚。仅仅因为编译器使用类型擦除实现泛型并不排除文档包含泛型类型参数。泛型和文档是为人服务的，而字节码是为 JVM 服务的。类型擦除更强烈地落在 JVM 方面，所以这里没有密切关系。
在我遇到的一个案例中，它描述了参数的类型，链接看起来像{@link List<Customer>}。如果你删除它，javadoc 最终只是将参数描述为一个列表。这对呼叫者没有任何信息。为什么要让它成为一个链接？所以他们可以点击它。在这种情况下，一个很好的解决方案是{@link List}&lt;{@link Customer}&gt;，它可以让他们点击指向列表或客户的链接，具体取决于他们想要查看的内容。
java doc 的目的是提供有关设计过程中预期内容的数据。因此，我也强烈认为 Javadoc 应该允许泛型，向开发人员提供所有信息，以了解期望返回什么或提供什么作为参数。
前两段需要额外限定。参数化类型是编译时方法签名的一部分。在编译期间，类型擦除将具有参数化类型的签名映射到具有原始类型的签名。例如，参见 JLS 4.6：类型擦除。
我倾向于通过这样做来解决这个问题：{@link EventHandler}{@code }

【解决方案2】：

类似于 David Conrad 解决方案，您可以使用完整签名作为链接描述，使用语法：

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

记得转义< 和>。例如：

 {@link #parse(Map, String, String) parse(Map&lt;String, String&gt;, String, String)}

【讨论】：

那么这个返回类型应该如何记录？

【解决方案3】：

这可能不是您想要的，但我已经学会了忍受类似的东西 * @return {@link List} of {@link RfRequestSummaryDto}

【讨论】：

我见过几个库和框架这样做。在这一点上似乎是一个约定。