Bugzilla – Full Text Bug Listing
| Summary: | [hovering] Better support for inherited Javadoc comments correctly. | ||
|---|---|---|---|
| Product: | [Eclipse Project] Platform | Reporter: | Alan Boxall <boxall> |
| Component: | Text | Assignee: | Platform-Text-Inbox <platform-text-inbox> |
| Status: | CLOSED WONTFIX | QA Contact: | |
| Severity: | normal | ||
| Priority: | P3 | CC: | hudsonr, sdavids, tobias_widmer |
| Version: | 2.1 | ||
| Target Milestone: | --- | ||
| Hardware: | PC | ||
| OS: | Windows 2000 | ||
| Whiteboard: | stalebug | ||
JavaDoc supports to downcopy comments from base classes when they are overridden. To enable the downcopy you should not use a JavaDoc comment in the overridden method (this explains option 1). The common practice is therefore to not use JavaDoc comments in overridden methods (this explains option 2). The code generation support provides a setting for this style. What could be considered is to collect all the JavaDocs from overridden methods and present them to the user, but this is not for 2.0. Thanks for the explanation. I found the option to create non-javadoc comments. The pop-up comments are so valuable I am surprised that non-javadoc comments for overridden methods is not the default so that they show through. Even when I select to override a method the default is to create a javadoc comment. The one function missing if I enable this option is the ability to add my own comments to the ones that appear in the overridden method. It appears that non- javadoc comments don't appear in the code assist pop-up. Ultimately, I would like to see the javadoc comments collected and presented to the user. BTW, I now comment my code more because of this feature!! Thanks for the feedback, collecting the inherited javadocs is tempting. If we can sneak it in we will. Reopen for investigation "Unassign" PRs because of changes in staffing As of JDK 1.4 one can use the {@inheritDoc} tag.
So instead of:
/* (non-Javadoc)
* @see java.lang.Object#toString()
*/
public String toString() {
return super.toString();
}
One could write:
/**
* {@inheritDoc}
*/
public String toString() {
return super.toString();
}
@@@@
Just change the template in Java/Code Generation/Code and
Comments/Comments/Overriding Methods.
@@@@
If JDK 1.4 is the new "default" JDK version ... than the the {inheritDoc} could
be used for the "default" Eclipse template.
This would also help JavaDoc check utilities ... "Does every method have a
JavaDoc?".
I adapted the summary. The Javadoc you see while using code assist is the same as when you hover over those methods. *** Bug 67659 has been marked as a duplicate of this bug. *** Comment #1 is incorrect. javadoc.exe will copydown descriptions in the presence of a Javadoc comment which does *not* contain its own description. How would you re-@deprecate an overridden method? *** Bug 128235 has been marked as a duplicate of this bug. *** This bug hasn't had any activity in quite some time. Maybe the problem got resolved, was a duplicate of something else, or became less pressing for some reason - or maybe it's still relevant but just hasn't been looked at yet. If you have further information on the current state of the bug, please add it and remove the stalebug whiteboard tag. The information can be, for example, that the problem still occurs, that you still want the feature, that more information is needed, or that the bug is (for whatever reason) no longer relevant. -- This bug hasn't had any activity in quite some time. Maybe the problem got resolved, was a duplicate of something else, or became less pressing for some reason - or maybe it's still relevant but just hasn't been looked at yet. If you have further information on the current state of the bug, please add it and remove the stalebug whiteboard tag. The information can be, for example, that the problem still occurs, that you still want the feature, that more information is needed, or that the bug is (for whatever reason) no longer relevant. - I'm ok if you close this as no longer an issue or fixed elsewhere. I have been writing Java code all this time and it seems to be working in a way that shows me the comments I need in the hover. |
Drop M5 (4/16) The problem is that when I use code assist the comment I see beside the method depends on the format of the method's comment. Example: I have 2 methods (that implement an interface) declared as follows: The first one was created using "Add Javadoc comment". The 2nd method declaration differs in the first line of the method comment. /* instead of /** /** * @see IMyInterface#myMethodA() */ public void myMethodA() { ... body } /* * @see IMyInterface#myMethodB() */ public void myMethodB() { ... body } When I use code assist on myMethodA() I will see an empty description and "See also: IMyInterface.myMethodA" When I use code assist on myMethodB() I will see the comments from the overridden method in the interface. This is much better than the first case. The problem with the 2nd option is that are forced to create comments that are not proper javadoc format so that the end user can see the comments from the overridden method. As a Java coder I would like to see under "See also" the comments from the overridden method, not "see also ...."