[jira] Closed: (WICKET-3221) don't use @see upperClass when javadoc inheritance is sufficient

["Peter Ertl (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/WICKET-3221?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Peter Ertl closed WICKET-3221.
------------------------------

    Resolution: Fixed

This issue was more of a discussion that a real problem to fix. Since there is no easy way of measuring if the issue is solved or not I am closing it.

> 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.