How to add reference to a method parameter in javadoc?

Question

Is there a way to add references to one or more of a method's parameters from the method documentation body? Something like:

/**
 * 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)
{...}

score 429 · Accepted Answer · edited May 25 '16 at 07:10

429

As far as I can tell after reading the docs for javadoc there is no such feature.

Don't use <code>foo</code> as recommended in other answers; you can use {@code foo}. This is especially good to know when you refer to a generic type such as {@code Iterator<String>} -- sure looks nicer than <code>Iterator<String></code>, doesn't it!

edited May 25 '16 at 07:10

Jacek Laskowski

72,696
27
242
420

answered Nov 04 '09 at 00:50

Kevin Bourrillion

40,336
12
74
87

2

`@code` tag is described in [Javadoc - Tag Descriptions](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html). See [Sample usage in JDK8 code](http://hg.openjdk.java.net/jdk8u/jdk8u60/jdk/file/tip/src/share/classes/java/lang/String.java#l172). – pba Sep 06 '19 at 07:33
7

How is it not possible to reference a method's own parameters within the docs of the method. Swing and a miss, Java! – Josh M. Mar 11 '22 at 22:08

score 89 · Answer 2 · answered Jan 13 '17 at 11:34

89

The correct way of referring to a method parameter is like this:

answered Jan 13 '17 at 11:34

Eurig Jones

8,226
7
52
74

59

Not only does it answer the question, but it visually explains how to amend Javadoc with a parameter using an IDE such as Intellij. This will be useful for searchers who are looking for an answer. – Eurig Jones Apr 07 '17 at 23:32
2

On Eclipse it doesn't work. But it's a nice answer nonetheless – Henrique de Sousa Aug 08 '17 at 09:38
2

this should be deleted. imagine no longer exists. – user4504267 Nov 16 '17 at 17:38
3

@user4504267 Image looks fine, at least now. – ErikE May 30 '18 at 16:28
2

Try to refactor param name, intellij won't update this code blocks. – m1ld Nov 09 '18 at 09:54
I just realized that the preview did not work for me since I was trying to refer one parameter from within the @param description of another instead of the javadoc body. – Simeon Jul 19 '21 at 12:11
@m1ld That's because this simply formats the text as `code`. It does not actually link to the parameter name in any way, unlike the C# [paramref](https://learn.microsoft.com/en-us/dotnet/visual-basic/language-reference/xmldoc/paramref) tag. – Mike Lowery Aug 31 '22 at 22:50
Despite the pretty picture, ignore this answer and see the accepted answer from @kevin-bourrillion because it says to do the same thing but notes that it is only a workaround as no such feature exists (... and so you should not expect an actual link or for refactoring to update it etc.). – SensorSmith Aug 01 '23 at 16:30

score 68 · Answer 3 · edited Jul 24 '21 at 23:24

As you can see in the Java Source of the java.lang.String class:

/**
 * 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);
}

Parameter references are surrounded by <code></code> tags, which means that the Javadoc syntax does not provide any way to do such a thing. (I think String.class is a good example of javadoc usage).

The tag is not referencing a specific parameter. It is formatting the word "String" into "code looking" text. — Naxos84, Mar 09 '17 at 06:01
@Naxos84 that's true for the first tag, but further on in the javadoc they reference `offset` and `count` parameters surrounded by tags — Caleb Hulbert, Jan 04 '22 at 17:53

score 13 · Answer 4 · answered Nov 03 '09 at 13:25

13

I guess you could write your own doclet or taglet to support this behaviour.

Taglet Overview

Doclet Overview

answered Nov 03 '09 at 13:25

jitter

53,475
11
111
124

27

And make a pull request to javadoc :) – Juh_ Nov 05 '14 at 13:08

score -2 · Answer 5 · edited Jul 14 '22 at 10:06

-2

Here is how it is written in Eclipse Temurin JDK 8 sources:

It looks like the only way is or {@code }, but it's not a link - it's just formatting.

edited Jul 14 '22 at 10:06

Community

1
1

answered Feb 03 '22 at 12:02

Mic

105
1
6

So.. other than under `Params:` section, where is `x` located in the javadoc description of `println` ? – Afriza N. Arief Jul 09 '22 at 16:52
1

This is an incorrect answer! `{@link #method(parameters)}` works only for a link to other methods of the same class, not to the parameters of the same method, which was the question. – Honza Zidek Jul 13 '22 at 09:27

How to add reference to a method parameter in javadoc?

5 Answers5

Linked