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

["Pedro Santos (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/WICKET-3221?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12966552#action_12966552 ] 

Pedro Santos edited comment on WICKET-3221 at 12/3/10 10:48 AM:
----------------------------------------------------------------

+1
Refactor an method or class name on eclipse also renames the @see link on javadoc. But I think the code would be cleaner without an javadoc at the class code just for the @see tag

      was (Author: pedrosans):
    +1
Refactor an name class on eclipse also rename the @see on javadoc. But think the code would be cleaner without an javadoc just for the @see tag
  
> 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.