You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@wicket.apache.org by "Peter Ertl (JIRA)" <ji...@apache.org> on 2010/12/02 23:16:12 UTC
[jira] Created: (WICKET-3221) don't use @see upperClass when
javadoc inheritance is sufficient
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.
[jira] Commented: (WICKET-3221) don't use @see upperClass when
javadoc inheritance is sufficient
Posted by "Juergen Donnerstag (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/WICKET-3221?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12966634#action_12966634 ]
Juergen Donnerstag commented on WICKET-3221:
--------------------------------------------
The same seems to be true for Interface implementations.
Instead of removing the comment alltogether, an "empty" comment seem to work as well, at least in eclipse
/**
*
*/
I personnelly like the visual separation provided by a comment on top of the method.
> 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.
[jira] Commented: (WICKET-3221) don't use @see upperClass when
javadoc inheritance is sufficient
Posted by "Juergen Donnerstag (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/WICKET-3221?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12966806#action_12966806 ]
Juergen Donnerstag commented on WICKET-3221:
--------------------------------------------
Inheritance doesn't seem to be working for ctors
> 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.
[jira] Updated: (WICKET-3221) don't use @see upperClass when
javadoc inheritance is sufficient
Posted by "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 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.
[jira] Closed: (WICKET-3221) don't use @see upperClass when javadoc
inheritance is sufficient
Posted by "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.
[jira] Commented: (WICKET-3221) don't use @see upperClass when
javadoc inheritance is sufficient
Posted by "Martin Grigorov (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/WICKET-3221?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12966554#action_12966554 ]
Martin Grigorov commented on WICKET-3221:
-----------------------------------------
+1
generated javadocs also show the parent's javadoc when available
mvn javadoc:javadoc showed a lot of warnings. We have to clean this area before 1.5 GA
> 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.
[jira] Commented: (WICKET-3221) don't use @see upperClass when
javadoc inheritance is sufficient
Posted by "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 commented on WICKET-3221:
--------------------------------------
+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.
[jira] Issue Comment Edited: (WICKET-3221) don't use @see
upperClass when javadoc inheritance is sufficient
Posted by "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.