Community
Participate
Working Groups
20041130 To document a type parameter, the normal @param tag is used, but with angle brackets. /** * @param <X> */ <X> void foo() { } The AST currently just returns a TagElement with a sigle children Name 'X' and is currently not distinguishable from a normal parameter. Either text elements '<' and '>' are inserted or we use a SimpleType node instead of the SimpleName. The first suggestion would make the accessing of tag names more complicated. The drawback of the second suggestion is that it does not include the source ranges for the open and closing angle brackets, but users can use the scanner as soon as they see the SimpleType instead of the SimpleName. The deluxe solution would be a new node type that includes the bracket and has a simple name.
Jin, you also might be interested in that..
Thanks Martim :-) I think your first suggestion, to render it as { TextElement("<"), SimpleName("X"), TextElement(">"), TextElement("the rest") }, makes the most sense. This exposes the simple type variable for its binding, and keeps the "<" and ">" delimiters separate. The second suggestion has the disadvantage of leaving non-whitespace unaccounted for. The deluxe solution is possible, but it seems a waste to introduce a new node type for that purpose only, especially when there's a workable alternative.
I see from http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/whatsnew- 1.5.0.html that there are other 1.5 changes that will affect our parsing of Javadoc tags: there are new {@code} and {@literal} tag elements which are notable in that the text string is taken literally (i.e., not as HTML); and the {@value} tag element can now contain a member reference.
Added TagElement.TAG_CODE and TAG_LITERAL constants.
Jeem, Solution 2 (ie. use a SimpleType instead of SimpleName) is not currently possible as SimpleType does not implement IDocElement... Is it ok to add this interface to SimpleType or finally do we have to create a new node?
Another solution would be to use a TypeParameter instead of SimpleType, but we always have the problem of IDocElement interface...
Forget previous comment... It seems not to be a good idea...
Jeem, About new tags (comment 3): - @value: new syntax is scanned correctly by the parser since M2 (bug 70892) - @code and @literal do not change anything for compiler and are correctly parsed by DocCommentParser Following test case produce correct dom/ast hierarchy for javadoc nodes (positions and bindings): /** * New tags for 5.0 * - literal: {@literal a<B>c} * - code: {@code abc} * - value: {@value System#out} */ public class Test { }
hum, also forget my comment 5 (perhaps it's not a good idea to work on Sunday...) as Jeem and Martin agreed on solution 1... I'll rewrite the fix to implement it...
Fixed. Range now includes closing '>'. [jdt-core-internal] Changes done in: - Javadoc.getNodeStartingAt(int) - AbstractCommentParser.parseParam(). - JavadocParser.pushParamName(boolean) - DocCommentParser.pushParamName(boolean) Test cases added: - ASTConverterJavadocTests#testBug79809() - ASTConverterJavadocTests#testBug79809b()
Copy/Paste error.... You should read: Fixed. Now TagElement has required children: { TextElement("<"), SimpleName("X"), TextElement(">"), TextElement("the rest") }. SimpleName binding is the binding of the type variable 'E'. [jdt-core-internal] ...
Verified in 200412140800
