Community
Participate
Working Groups
Build ID: HEAD as of 7/19/2007 I am writing the javadoc comment for an annotation class, and I want to give an example of how to use the annotation. If I just write it out as-is with the @ sign, both javadoc and JDT think it's a Javadoc tag; javadoc(1) complains that it's unknown and JDT that it's invalid. Thus, I replaced the @ with @ as suggested by Sun's javadoc(1) man page. The entity works fine in the generated javadoc and in hovers, but the source formatter expands it back to @, causing the problem again. I can understand wanting to expand entities as a cleanup, but as a special case, the source formatter needs to be taught never to expand @ in javadoc because that could cause something to be misinterpreted as a javadoc tag. Steps To Reproduce: 1. Activate the Package Explorer, deselect everything, and paste the following code: /** * Here's an example of how to use this annotation: * * <pre> * @Coolness("extreme") class Foo {} * </pre> */ public @interface Coolness { String value(); } 2. Format the source file that opens (Source -> Format). A warning appears on the annotation inside the <pre>.
Oops, I forgot a step: 1/2. Go to Window -> Preferences -> Java -> Compiler -> Javadoc and ensure that "Malformed Javadoc comments" is set to at least Warning.
Created attachment 74826 [details] Fix This patch fixes the bug by changing Java2HTMLEntityReader to translate a @ back to a @ when it is the first thing on a line.
I can't recommend the use of @ until bug 198153 is also fixed because the formatter adds another space before the @ each time you format the code.
Created attachment 74955 [details] Add regression test This patch applies on top of my regression test for bug 198153.
Released for 3.4M1. Added regression test in org.eclipse.jdt.core.tests.formatter.comment.JavaDocTestCase#test197169 Thanks for the contribution.
Verified for 3.4M1 using build I20070806-1800.
Jérôme, The fix for this bug is also required to be backported for 3.3.1 in order to properly backport bug 109636. +1 for 3.3.1 ?
+1 for backporting to 3.3.1
Reopen for 3.3.1.
Released for 3.3.1. Added regression test in org.eclipse.jdt.core.tests.formatter.comment.JavaDocTestCase#test197169
Verified for 3.3.1 using build M20070831-2000.