Javadoc - 如何复制功能描述？答案

【问题标题】：Javadoc - how to copy function description?Javadoc - 如何复制功能描述？
【发布时间】：2011-07-25 22:58:40
【问题描述】：

我有两个 Java 函数：

/**
* Do something with param
*/
public String doSomething(String param) {...};

/**
* ...
*/
public String doSomething(Integer param) {...};

如何使第二个函数的描述显示第一个函数的精确副本？

【问题讨论】：

【解决方案1】：

假设复制和粘贴对你不起作用，我相信惯例是使用@see 标签来引用另一种方法，它会提供更多详细信息。

在您的示例中，doSomething(Integer param) 将有一个引用字符串版本的 @see 标记。

【讨论】：

【解决方案2】：

简短的回答是你不能。习惯是使用@see 指令或简单地复制粘贴。

如果您是子类化，您可以将 javadoc 放在接口级别，而不是实现您想要的。

【讨论】：

【解决方案3】：

因为两种不同类型参数的方法不能有相同的描述。但是对于继承的方法，我们可以使用相同的描述。

继承方法

对于继承的方法你可以使用

{@inheritDoc}

它从被覆盖的方法中复制描述。

【讨论】：

【解决方案4】：

你不想那样做。您希望第二个引用第一个。这就是@see 的用途。您永远不想重复文档，因为您的第二个方法调用第一个方法而不是包含其代码的副本。

【讨论】：

【解决方案5】：

不要只使用{@see ...}，它有不同的含义并且存在一些问题（比如不能覆盖继承的文档）。

斯巴达式的/** See: {@link ...}. */ 更好。

但是，最好是添加一些文本，而不仅仅是“查看”。简要描述此方法的意图及其具体内容，并{@link ...} 描述详细解释完整合同的方法。这通常在 JDK 和其他库中完成，是一种很好的做法。

例如：

/**
 * Does something very important.
 * For details see {@link #doSomething(Integer)}.
 */

或：

/**
 * Does something very important.
 * Equivalent to calling {@link #doSomething(Integer) doSomething(0)}.
 */

【讨论】：