Description Brian Wilkerson 2002-04-03 14:18:36 EST

Given a class whose source code has the following form:

public abstract class TestClass implements ITestClass {
    /* (non-Javadoc)
     * @see ITestClass#getName()
     */
    public String getName() {
        return null;
    }
}

invoking the method

    org.eclipse.jdt.core.IType.createField(String contents,
                                           IJavaElement sibling,
                                           boolean force,
                                           IProgressMonitor monitor)

on the object that represents the above type (passing in "null" for both the 
sibling and the progress monitor and "false" for force) will cause the 
definition of the field to be inserted between the comment and the method. I 
suspect that the behavior I'm seeing is due to the non-Javadoc comment not 
being associated with the method.

This behavior seems inconsistent because of the user-level preference 
to "Create non-Javadoc comments for overridden methods" on the Java|Code 
Generation preference page. It seems that the user interface is implying 
support for that style of coding, while the API does not. I believe that in 
order to fully support that style, the API needs to recognize such a comment as 
being essentially equivalent to a Javadoc comment.

I believe that two fixes are possible. The first would be to explicitly stop 
supporting that style of coding. I suspect, however, that while this change 
would be easy to implement, it would be a very difficult change to make from a 
political point of view.

The second would be to fix the API so that non-Javadoc comments are associated 
with the member (or at least method) that follows them. You might want to place 
additional restrictions so that the association is only made if

 - there are no blank lines between the comment and the member,

 - there is no Javadoc comment, and/or

 - the phrase "(non-Javadoc)" must appear as the first non-white
   space in the comment.

I am running build 20020214 under Microsoft Windows 2000 (5.00.2195).