Refactorable reference to a method parameter in javadoc

Question

How do I make a reference, in javadoc, to a method parameter, so that the reference can be refactored ?
For example:

public class A {

    private int field;

    /**
     * @param p 
     * {@link #field} is initialized using the value of p.
     */
    void foo(int p)
    {
        //...

    }
}

If I rename parameter p in the above code, I want

"...using the value of p"

text to change accordingly (just as renaming field will change {@link #field} ).
I read this old post, and some more sources, but could not find a way to do it.
Does javadoc support it ?

The Q&A you linked to states pretty clearly that there is no such feature in JavaDoc. Why should this question not be closed as a duplicate? — E-Riz, Aug 23 '16 at 14:06

score 3 · Accepted Answer · answered Aug 22 '16 at 11:34

Due to Java erasure, method argument names are ephemeral, they are not part of the static class definition. So, void foo(int p) being changed to void foo(int x) is not considered refactoring, because it is guaranteed that it will not affect the program's logic in any way (unless the argument is overloading a class field).

So in the javadoc there cannot be a static link that identifies the method argument. The mere fact that the word after @param changes when you refactor the method is a favor offered by the IDE.

score 3 · Answer 2 · answered Aug 25 '16 at 19:31

3

Your IDE will be able to refactor the name if you put it after @param (tested in Eclipse), but not if you refer to it elsewhere within the comment. From a language perspective, there's no reason to do this. Why not just write @param p {@link #field} is initialized using this value.?

answered Aug 25 '16 at 19:31

Rand

321
1
6

1

Thank you for your answer. Yes, I know that it will work for `@param p and some text` . It doesn't work for `some text @param p` – c0der Aug 26 '16 at 06:29

Hamid · Answer 3 · 2017-06-14T19:40:52.617

IntelliJ IDEA will refactor the parameter name anywhere in the JavaDoc comment as long as you place it in curly brackets, e.g. {@param p}

/**
 * @param p 
 * {@link #field} is initialized using the value of {@param p}.
 */

Also, Java's type erasure (as mentioned in the accepted response) has nothing to do with the scope of variable names. Type erasure is the compromise that Java designers implemented in order to add Java Generics but still keep the language backward compatible. All parameterization of generics is erased - none of it actually makes it to the byte code. This is why Java Generics are so limited - you can't for example do

T myT = new T();

if T is a parametrized type, because at runtime all information about T has already been erased.

He's not talking about generic type erasure, he's talking about erasure in general - and parameter names are indeed erased. — toolforger, Feb 22 '21 at 08:04

score 1 · Answer 4 · answered Aug 22 '16 at 14:11

1

Have you tried to configure eclipse javadoc preferences? Window->Preferences, Java->Compiler->Javadoc. Check the Process Javadoc comments option.

Also if you check Window->Preferences->Java->Editor->Typing->Javadoc and comment regions+Add Javadoc tags it will add the appropiated javadoc tags. Once you have both activated Eclipse will warn you about the mistaken parameters and you can use ctrl1 to "quick-fix" it.

answered Aug 22 '16 at 14:11

Tena

600
4
14

3

Thank you for the answers. These options are helpful. They do not help with the issue I raised. – c0der Aug 23 '16 at 04:30

Refactorable reference to a method parameter in javadoc

4 Answers4