don't use @see upperClass when javadoc inheritance is sufficient
----------------------------------------------------------------
Key: WICKET-3221
URL: https://issues.apache.org/jira/browse/WICKET-3221
Project: Wicket
Issue Type: Improvement
Components: wicket
Affects Versions: 1.5-M3
Reporter: Peter Ertl
I see this all the time:
/**
* @see java.util.LinkedHashMap#removeEldestEntry(java.util.Map.Entry)
*/
@Override
protected boolean removeEldestEntry(final Map.Entry<K, V> eldest)
The javadoc links to the parent javadoc using @see.
This is not required since javadoc inheritance is enabled by default. Unless
you want to modify the javadoc from the parent class it's sufficient to just
don't declare javadoc at all. less work and better result!
@Override
protected boolean removeEldestEntry(final Map.Entry<K, V> eldest)
will automatically inherit the javadoc from the method it overrides.
Quite often the @see link is broken after refactoring.
So the @see generates a lot of unnessecary work (fix links after refactors) and
makes javadoc less usable.
Shouldn't we just abandon that style of documentation if the parent javadoc is
fine for the child?
??
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
