[riena-dev] Suggestion: avoid "@see xyz"-only comments

["Volanakis, Elias" <evolanakis@xxxxxxxxxxxxxx>]

Hi,

I recently came across several javadoc comments like this:

/**
 * @see org.eclipse.riena.ui.ridgets.IRidget#updateFromModel()
 */
public void updateFromModel() {


I suggest avoiding those kind of comments in the future (unless there is
additional text).

Here's why: When one generates the java doc or when one uses the mouse
to hover over a method like "myRidget.updateFromModel()" in Eclipse, you
_only_ see the text "@see org.eclipse.riena......" in the tooltip. 

It is much better to use a plain (green) comment, or leave the javadoc
completely empty. This results in the documentation being inherited from
the parent method. In that case hovering over the same method shows the
actual text in the tooltip: "For value based ridgets triggers an update
from the model value to theRidget... etc...". The same applies for the
generated javadoc.


These styles inherit doc from parent:

/*
 * @see org.eclipse.riena.ui.ridgets.IRidget#updateFromModel()
 */
public void updateFromModel() {

or

public void updateFromModel() {



What do you think? 

Thanks,
Elias.