Bug 68772 - IDOMMember.getComments() sometimes returns wrong results.
Summary: IDOMMember.getComments() sometimes returns wrong results.
Status: RESOLVED FIXED
Alias: None
Product: JDT
Classification: Eclipse Project
Component: Core (show other bugs)
Version: 3.0   Edit
Hardware: All All
: P3 normal (vote)
Target Milestone: 3.0.1   Edit
Assignee: Frederic Fusier CLA
QA Contact:
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2004-06-28 12:07 EDT by Paul Elder CLA
Modified: 2004-09-06 10:23 EDT (History)
0 users

See Also:

Attachments
JUnit test cases illustrating the defect (6.09 KB, application/x-zip-compressed)
2004-06-28 12:10 EDT, Paul Elder CLA 		no flags Details
Proposed Fix to DOMBuilder.java (5.02 KB, application/x-zip-compressed)
2004-06-28 12:11 EDT, Paul Elder CLA 		no flags Details
Patch to apply in 3.0 maintenance stream (3.15 KB, application/octet-stream)
2004-06-29 12:45 EDT, Frederic Fusier CLA 		no flags Details
Show Obsolete (2) View All 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 Paul Elder CLA 2004-06-28 12:07:01 EDT 
IDOMMember.getComments() appears to attempt to return the "doc comment" (that
is, the Javadoc comment) for the member. The documentation is vague on this, but
testing seems to suggest this is the intent.

However, in cases where a member has more than one /** */-style comment, unusual
results occur. For example, for in the following Java:

   /**
    * a first Javadoc comment
    */
   // public void foo() {
   // }
   /**
    * a second Javadoc comment
    */
   public void bar() {}

getComments() returns:

   /**
    * a first Javadoc comment
    */
   // public void foo() {
   // }
   /**
    * a second Javadoc comment
    */

This is inconsistent with the following example:

   // a non-javadoc comment
   /**
    * The javadoc for this
    */
   /*
    * another non-javadoc
    */
   public void foo() {}

in which case, getComments() returns:

   /**
    * The javadoc for this
    */

In general, getComments() returns everything between the first and last detected
javadoc-style comment for an element.

This is inconsistent with the way javadoc itself works. Javadoc uses only the
last javadoc comment immediately preceding the element.

The current behavior is the result of code in the
org.eclipse.jdt.internal.com.jdom.DOMBuilder methods enterAbstractMethod(),
enterField() and enterType(). Proposed fixes and JUnit tests will be attached.
Comment 1 Paul Elder CLA 2004-06-28 12:10:30 EDT 
Created attachment 12863 [details]
JUnit test cases illustrating the defect
Comment 2 Paul Elder CLA 2004-06-28 12:11:31 EDT 
Created attachment 12864 [details]
Proposed Fix to DOMBuilder.java

Fixes are flagged by a // FIXME comments.
Comment 3 Frederic Fusier CLA 2004-06-28 12:50:14 EDT 
IDOMMember has been deprecated in 3.0. As you opened this bug against 3.0, would
it be possible to use DOM/AST nodes API which does not have this problem?
Comment 4 Paul Elder CLA 2004-06-28 13:23:29 EDT 
I'm aware JDOM is deprecated in 3.0. Unfortunately, I uncovered it while using 
EMF/JMerge which makes extensive use of JDOM. I have proposed a workaround to 
them (see Bugzilla #68396, if you want details).

There is no point in you fixing this one if EMF does not fix 68396.

Longer term, EMF/JMerge will have to be re-written to use AST/DOM, but this 
will be non-trivial.
Comment 5 Philipe Mulet CLA 2004-06-29 05:53:42 EDT 
Frederic - pls address in 3.0 stream. Will deliver along with next rollup.
Comment 6 Frederic Fusier CLA 2004-06-29 06:04:09 EDT 
Proposed fix looks good and pass all JDT/Core tests => no problem to put it in
next rollup...
I'll also add proposed tests to JDOM tests.
Comment 7 Frederic Fusier CLA 2004-06-29 12:40:19 EDT 
Fixed and released in JDK_1_5 stream and will be available in Cheetah06.

New test class was added for additional tests:
org.eclipse.jdt.tests.core.DOMTestsComments

All test cases have been externalized in java file and put in a new project
"CommentsTests" in "TestSolution" workspace...
Comment 8 Frederic Fusier CLA 2004-06-29 12:45:16 EDT 
Created attachment 12881 [details]
Patch to apply in 3.0 maintenance stream

These patches (jdt.core + jdt.core.tests) will be released in 3.0 maintenance
stream when corresponding branch will be created in dev.eclipse.org repository.


Note that these patches have been created on top of v_449 version which matches
Eclipse 3.0 delivery...
Comment 9 Frederic Fusier CLA 2004-06-29 13:20:35 EDT 
Fixed and released in HEAD stream.
Comment 10 David Audel CLA 2004-09-06 10:23:31 EDT 
Verified for 3.0.1 RC1