| RE: [riena-dev] Suggestion: avoid "@see xyz"-only comments |
Hello Elias,
> 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?
If only Eclipse would support the {@inheritDoc} tag properly, the follwing style would probably give us the best of both worlds:
/*
* {@inheritDoc}
* @see org.eclipse.riena.ui.ridgets.IRidget#updateFromModel()
*/
public void updateFromModel() {
Javadoc supports it, IntelliJ IDEA supports it, I'm not sure about Netbeans, but over and over annoyed by the fact that Eclipse doesn't, still hoping for a future release which does.
Regards,
Wanja