如何在javadoc中为方法参数添加引用？

Question

有没有一种方法可以从方法文档正文中添加对一个或多个方法参数的引用？类似于：

/**
 * When {@paramref a} is null, we rely on b for the discombobulation.
 *
 * @param a this is one of the parameters
 * @param b another param
 */
void foo(String a, int b)
{...}

- ripper234

Answer 1

据我所知，在阅读了javadoc文档后，没有这样的功能。

不要像其他答案中建议的那样使用<code>foo</code>；你可以使用{@code foo}。当您引用泛型类型（例如{@code Iterator<String>}）时，这一点尤其重要 - - 确实比<code>Iterator&lt;String&gt;</code>好看！

- Kevin Bourrillion

---

@code 标签在 Javadoc - Tag Descriptions 中有描述。 请参见 JDK8 代码示例。 - pba

在方法文档中引用该方法自己的参数是不可能的。Java，你这次失败了！ - Josh M.

Answer 2

正确的引用方法参数的方式如下所示：

- Eurig Jones

---

它不仅回答了这个问题，而且还通过视觉演示使用像Intellij之类的IDE来修正Javadoc中的参数，这将对寻找答案的搜索者有所帮助。 - Eurig Jones

在Eclipse上它不起作用。但无论如何这是一个很好的答案。 - Henrique de Sousa

这应该被删除。想象它已经不存在了。 - user4504267

@user4504267 图像看起来不错，至少现在是这样。 - ErikE

尝试重构参数名称，IntelliJ不会更新这些代码块。 - m1ld

Answer 3

正如你可以在Java源代码的java.lang.String类中看到：

/**
 * Allocates a new <code>String</code> that contains characters from
 * a subarray of the character array argument. The <code>offset</code>
 * argument is the index of the first character of the subarray and
 * the <code>count</code> argument specifies the length of the
 * subarray. The contents of the subarray are copied; subsequent
 * modification of the character array does not affect the newly
 * created string.
 *
 * @param      value    array that is the source of characters.
 * @param      offset   the initial offset.
 * @param      count    the length.
 * @exception  IndexOutOfBoundsException  if the <code>offset</code>
 *               and <code>count</code> arguments index characters outside
 *               the bounds of the <code>value</code> array.
 */
public String(char value[], int offset, int count) {
    if (offset < 0) {
        throw new StringIndexOutOfBoundsException(offset);
    }
    if (count < 0) {
        throw new StringIndexOutOfBoundsException(count);
    }
    // Note: offset or count might be near -1>>>1.
    if (offset > value.length - count) {
        throw new StringIndexOutOfBoundsException(offset + count);
    }

    this.value = new char[count];
    this.count = count;
    System.arraycopy(value, offset, this.value, 0, count);
}

参数引用需要用<code></code>标签括起来，这意味着 Javadoc 语法没有提供任何方法来执行此操作。（我认为 String.class 是 javadoc 的一个很好的使用示例。）

- Lastnico

---

<code></code> 标签并没有引用特定的参数，它是将单词 "String" 格式化为看起来像代码的文本。 - Naxos84

@Naxos84，对于第一个<code></code>标签是正确的，但在javadoc中进一步引用了由<code></code>标签包围的offset和count参数。 - Caleb Hulbert

Answer 4

我想你可以编写自己的doclet或taglet来支持这种行为。

标签(Taglet)概述

文档生成器(Doclet)概述

- jitter

---

请向 javadoc 提交一个拉取请求。 - Juh_

Answer 5

以下是在Eclipse Temurin JDK 8源代码中的编写方式：

看起来唯一的方法是使用或{@code }，但它不是一个链接 - 它只是格式化。

- Mic

---

除了在“Params:”部分下面，println的javadoc描述中还有哪里可以找到x？ - Afriza N. Arief

这是一个错误的答案！{@link #method(parameters)}只适用于链接到同一类中其他方法，而不是链接到同一方法的参数，这也是问题所在。 - Honza Zidek