How to add reference to a method parameter in javadoc?

java arguments javadoc

146,822

Solution 1

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!

Solution 2

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

Solution 3

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).

Solution 4

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

Taglet Overview

Doclet Overview

View more solutions

146,822

Author by

ripper234

See blog or LinkedIn Profile

Updated on July 08, 2022

Comments

ripper234 almost 2 years

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

Juh_ over 9 years

And make a pull request to javadoc :)
Naxos84 over 7 years

The <code></code> tag is not referencing a specific parameter. It is formatting the word "String" into "code looking" text.
Eurig Jones about 7 years

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.
Henrique de Sousa almost 7 years

On Eclipse it doesn't work. But it's a nice answer nonetheless
user4504267 over 6 years

this should be deleted. imagine no longer exists.
ErikE about 6 years

@user4504267 Image looks fine, at least now.
m1ld over 5 years

Try to refactor param name, intellij won't update this code blocks.
pba almost 5 years

@code tag is described in Javadoc - Tag Descriptions. See Sample usage in JDK8 code.
Simeon almost 3 years

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.
Caleb Hulbert over 2 years

@Naxos84 that's true for the first <code></code> tag, but further on in the javadoc they reference offset and count parameters surrounded by <code></code> tags
Josh M. over 2 years

How is it not possible to reference a method's own parameters within the docs of the method. Swing and a miss, Java!