Community
Participate
Working Groups
The characters allowed in the tag name of a doc tag are more general than just a Java identifier. In particular, I came across J2EE examples recently of doc tags like @ejb.bean-interface-method prop1="x", prop2="y" We should investigate what Javadoc considers as the set of legal characters in a doc tag name, and make sure that AST.parse* handles these properly.
The original spec was the Javadoc from Sun: http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html which says: "... JAVADOC TAGS The Javadoc tool parses special tags when they are embedded within a Java doc comment. These doc tags enable you to autogenerate a complete, well-formatted API from your source code. The tags start with an "at" sign (@) and are case- sensitive -- they must be typed with the uppercase and lowercase letters as shown. A tag must start at the beginning of a line (after any leading spaces and an optional asterisk) or it is treated as normal text. By convention, tags with the same name are grouped together. For example, put all @see tags together. ..."
Consider for RC1 iff javadoc tool supports it. If not, defer post 3.0.
In fact Javadoc tool raises warnings for all unknown tags (ie. all tags which are not listed in spec - see http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#javadoctags). To avoid them, it is possible to specify -tag option which let Javadoc tool to accept custom tags... However, Javadoc tool does not accept custom tag when it includes one of the following character: !, ", #, %, &, ', -, :, <, > So, that means that we should accept all tag names with non-java identifiers character which are not invalid for Javadoc tool. This also means that the example provided by Jeem will be rejected as it contains the invalid character '-'...
Fixed. Accept now tag name with non-java identifier characters but valid for Javadoc tool. That means that following sample tags are now accepted: /** * @ejb(bean text... * @ejb)bean text... * @ejb*bean text... * @ejb+bean text... * @ejb,bean text... * @ejb.bean text... * @ejb/bean text... * @ejb;bean text... * @ejb=bean text... * @ejb?bean text... * @ejb[bean text... * @ejb]bean text... * @ejb^bean text... * @ejb{bean text... * @ejb|bean text... * @ejb~bean text... */ [jtd-core-internal] Change done in AbstractCommentParser.parseComment(int,int). Test case added in ASTConverterJavadocTests
Finally, we also accept characters which are scanned as token error by scanner. This allow following additional valid tags: /** * @ejb¦bean test non-java id character '¦' (val=166) in tag name * @ejb§bean test non-java id character '§' (val=167) in tag name * @ejb¨bean test non-java id character '¨' (val=168) in tag name * @ejb©bean test non-java id character '©' (val=169) in tag name * @ejb«bean test non-java id character '«' (val=171) in tag name * @ejb¬bean test non-java id character '¬' (val=172) in tag name * @ejb®bean test non-java id character '®' (val=174) in tag name * @ejb¯bean test non-java id character '¯' (val=175) in tag name * @ejb°bean test non-java id character '°' (val=176) in tag name * @ejb±bean test non-java id character '±' (val=177) in tag name * @ejb²bean test non-java id character '²' (val=178) in tag name * @ejb³bean test non-java id character '³' (val=179) in tag name * @ejb´bean test non-java id character '´' (val=180) in tag name * @ejb¶bean test non-java id character '¶' (val=182) in tag name * @ejb·bean test non-java id character '·' (val=183) in tag name * @ejb¸bean test non-java id character '¸' (val=184) in tag name * @ejb¹bean test non-java id character '¹' (val=185) in tag name * @ejb»bean test non-java id character '»' (val=187) in tag name * @ejb¼bean test non-java id character '¼' (val=188) in tag name * @ejb½bean test non-java id character '½' (val=189) in tag name * @ejb¾bean test non-java id character '¾' (val=190) in tag name * @ejb¿bean test non-java id character '¿' (val=191) in tag name * @ejb×bean test non-java id character '×' (val=215) in tag name * @ejb÷bean test non-java id character '÷' (val=247) in tag name */
Verified in 200405281200
