Making JavaDoc robust against refactoring

Question

I'm working on an application which is constantly refactored to improve it. Now, if we rename a certain class to better capture its intention, all the documentation mentioning the class does not get updated automatically, unless you use links ({@link ClassName}) to refer to the class.

JavaDoc principles however state that one should "Use in-line links economically", since links stand out and draw the readers attention, which I find sensible. Also you can't link to parameters of a method.

Is there another way in JavaDoc to make comments more robust to refactoring I'm not aware of?

Answer 1

When using eclipse to do refactoring you can search through string references in things like xml files as well.

Press Shift-Alt-R twice to get the dialog box. (On Macs it is Option-Command-R twice )