This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.

Bug 7115 - [Synchronization] Interface synchronization of javadoc comments inconsistent
Summary: [Synchronization] Interface synchronization of javadoc comments inconsistent
Status: CLOSED FIXED
Alias: None
Product: java
Classification: Unclassified
Component: Unsupported (show other bugs)
Version: -S1S-
Hardware: PC Windows ME/2000
: P3 enhancement (vote)
Assignee: issues@java
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2000-07-19 23:23 UTC by Steven Richman
Modified: 2007-09-26 09:14 UTC (History)
2 users (show)

See Also:
Issue Type: DEFECT
Exception Reporter:

Attachments
Add an attachment (proposed patch, testcase, etc.)

Note You need to log in before you can comment on or make changes to this bug.
Description Steven Richman 2000-07-19 23:23:28 UTC 
When you create a new class that implements an interface, javadoc comments for
the interface methods are synchronized. If the javadoc comments in the
interface change, though, the versions in the implementing classes are not
updated (the user is not prompted to synch, and manual synch doesn't update
them). This should probably be consistent: if you're going to synchronize
javadoc comments, keep them up-to-date.
Comment 1 Svata Dedic 2000-07-31 11:35:59 UTC 
If the Synchronization code creates a new method in the class' code, it copies
all its attributes, including JavaDoc comment contents. The same holds true for
updating implementation according to an interface change; BUT JavaDoc comment
does not trigger the synchronization mechanism -- implementation is still
perfectly compilable.

I don't think that synchronization of comments is desirable, because a comment
of the interface method should explain purpose and usage of that method.
Implementations should add their own peculiarities and comments (additional
restrictions, links to related methods,...) instead of blindly copying
interface's comment contents. The current behaviour (copy interface's JavaDoc
into implementation) can be seen as a bug.

If the implementation's comments are to be synchronized with the declaration
comment, only JavaDoc tags related to the method's declaration should be updated
(@return, @param, @throws); if the tag already exists, it should be updated iff
the text is exactly the same as in the interface's source (to prevent user
customizations from overwriting).
Comment 2 Svata Dedic 2000-08-08 13:21:59 UTC 
I'll keep the request as an enhancement (for clarification and better
specification of synchronization, at least).
Comment 3 Jan Becicka 2001-01-31 11:08:59 UTC 
*** Bug 8200 has been marked as a duplicate of this bug. ***
Comment 4 Jan Becicka 2001-01-31 11:09:59 UTC 
*** Bug 6135 has been marked as a duplicate of this bug. ***
Comment 5 Jan Becicka 2002-01-11 16:59:41 UTC 
Reopening for 3.4
Comment 6 Jesse Glick 2002-01-15 15:36:06 UTC 
IMHO: Javadoc comments should *never* be synchronized automatically,
and new impls should be given no comment. The Javadoc tool does a
perfectly good job of collecting superclass info; synching the
comments breaks this.
Comment 7 Svata Dedic 2002-05-21 17:50:15 UTC 
Cleaning up before 4.0 planning
Comment 8 Marek Grummich 2002-07-19 16:37:36 UTC 
Target milestone was changed from not determined to TBD
Comment 9 Jan Becicka 2003-01-07 15:12:38 UTC 
Changing to defect. See issue 27886
Comment 10 Svata Dedic 2003-01-08 12:06:01 UTC 
Fixed (comment synchronization removed).
Comment 11 Jesse Glick 2003-01-08 14:51:42 UTC 
See also issue #25429.
Comment 12 Jan Becicka 2003-01-21 11:01:18 UTC 
VERIFIED
Comment 13 Jesse Glick 2003-02-01 02:24:44 UTC 
BTW - cf. issue #30562.
Comment 14 Quality Engineering 2003-07-01 13:17:55 UTC 
Resolved for 3.4.x or earlier, no new info since then -> closing.