Community
Participate
Working Groups
I20040309 The Javadoc AST nodes have various problems with incomplete/erroneous javadoc tags, which causes problems when they have to be modified. Some TagElements are missing, and some appear inside others where they shouldn't. These findings were made with the help of the org.eclipse.jdt.astview plugin from http://www.eclipse.org/jdt/ > UI > Optional Plugins. ... /** * @param * @param tho {@link getList(int, long)} * @version throwaway * @param from 1st param of {@link A#getList(int, long, boolean) me} * @see #getList(Object, java.util.ArrayList) * @param from 2nd * @see #getList(int from, tho long) * @see #getList(int from, long tho) * @param * @return the list * @see #getList(..) * @param to * @throws .IOException * @deprecated * @throws IOException. * @todo it */ public ArrayList getList(int from, long to) throws IOException { ... (comment line:) (1) @param without name is not recognized as TagElement (2) the third fragment of @param tho ... is a TextElement with an invalid range "int, long)}". It should either be an @link tag or merged with the previous TextElement (3) TextElement fragment of @version includes the leading whitespace. (4) @link has MethodRef with false binding to getList(int, long) (5) @see also has false binding to getList(int, long) (7) the @see tag after "@param from 2nd" is not recognized as TagElement; the ")" of the @see tag is the third fragment of the previous @param tag. This is probably because there's no param "long" of type "tho" (9) like (1): @param is not a TagElement (11) like (7): @see is not a TagElement; previous @return TagElement has second TextElement with ".)" (13) @throws TagElement missing. TextElement "IOException" is 2nd fragment of previous @param to. The linebreak and "@throws ." are not represented anywhere. (15) "@throws IOException." is not a TagElement and is missing from the AST.
As it was said in bug 51600, javadoc tags which have syntax errors are not stored in AST javadoc node hierarchy. Let this bug as dependent of it instead of return as duplicate to verify that each problem (patiently noticed) will be fixed...
Note that point 3) is not really a problem: it works "as wanted". We decided to put in text following tag name even leading white spaces in order to have maximum of information in TextElement and avoid text rescan. For example in following example: @see Object Who does not Object? @see Object Who does not Object? @see Object Who does not Object? We do not need to rescan Javadoc text to know that these three tags are different and be able to print them exactly as they were written... So, this will not change for 3.0... Please open a new bug if you think that this behavior must be changed for some tags (@version for example...)
Note that point 5) is not a problem: it works "as wanted". When found reference is not applicable, we store the closest match we've found if one exist. Binding will be null only if we get no method at all (and in this case , the message will be "The method MMM is undefined..."). This behavior for references in Javadoc is the same than those found in code, so we do not plan to change it for 3.0... If you thing it should, then open a new bug addressing this issue...
All other problems were fixed when bug 51600 was fixed. However, I still do not resolve this bug as duplicate to be sure that all these tests are taken into account to validate bug 51600 implementation...
Test case added in ASTConverterJavadocTests.
Verified in 200405180816
