Javadoc reference param from another method

Question

I don't want to write redundant javadoc comments. As you can see, @param x is in a way redundant. Is there a javadoc markup to set a reference from @param x in class B to @param x in class A or am I allowed to just leave it out?

/**
 * Class A constructor
 * 
 * @param x  position on x-axis
 */
public A(final int x) {
    this.x = x;
}

/**
 * Class B constructor
 * 
 * @param x  position on x-axis
 * @param y  position on y-axis
 */
public B(final int x, final int y) {
    super(x);
    this.y = y
}

I would take a step back and ask why you are documenting parameters that appear to have an obvious meaning. If the code is self-documenting based on the names you choose, JavaDoc is largely irrelevant. — , Mar 09 '11 at 23:38
Note to myself: [{@inheritDoc}](http://docs.oracle.com/javase/1.4.2/docs/tooldocs/windows/javadoc.html#inheritingcomments) at least allows copying a doc of an overridden method. — Matthias, Sep 26 '12 at 15:40
Same for current method: http://stackoverflow.com/questions/1667212/reference-a-method-parameter-in-javadoc — Ciro Santilli OurBigBook.com, Feb 09 '15 at 13:43

score 3 · Accepted Answer · answered Mar 09 '11 at 21:08

You can't leave it out, javadoc isn't smart, it just parses the comments, he can't say that the x parameter for the B constructor is the same than the A constructor even if there is inheritance in play.

I don't think there's a way to "factorize" this either. You'll just have to write all of them, sorry...

score 1 · Answer 2 · answered Mar 09 '11 at 21:11

With methods it should work: if you overwrite or implement a method, the parameters are copied if not provided.

Constructors are not inherited, and even less to a constructor with other parameter types. Javadoc has no way to know that you pass the parameter to another constructor, since it does not interpret the contents of the methods/constructors, only the outer interface.

So, I suppose you are out of luck, if you don't want to write your own doclet or change the standard doclet (and even then you would have to somehow say which constructor to inherit the params from). (This would be a useful addition, also for multiple similar methods in the same class, I think.)

score 1 · Answer 3 · answered Mar 09 '11 at 22:36

1

If you're overriding a parent method, if you don't include the javadoc most IDEs will show the javadoc for the parent method instead. Otherwise there's no way to define/refer to variables in the javadoc syntax.

answered Mar 09 '11 at 22:36

sk.

6,336
5
38
46

Javadoc reference param from another method

3 Answers3