[
https://issues.apache.org/jira/browse/WICKET-3221?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Peter Ertl updated WICKET-3221:
-------------------------------
Description:
I see this all the time:
/**
* @see org.apache.wicket.Application#getApplicationKey()
*/
@Override
public final String getApplicationKey()
{
return getName();
}
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
public final String getApplicationKey()
{
return getName();
}
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?
??
was:
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?
??
> 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 org.apache.wicket.Application#getApplicationKey()
> */
> @Override
> public final String getApplicationKey()
> {
> return getName();
> }
> 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
> public final String getApplicationKey()
> {
> return getName();
> }
> 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.
