Trying to escape the “@” symbol in a {@code} block within a javadoc comment with Netbeans 8.0

问题

I'm trying to insert a {@code } annotation in a Javadoc comment using Netbeans 8.0 and it's not working properly.

I've seen other questions on this from before (i.e., How can you escape the @ character in javadoc?) but the html escape @ and {@literal @} both don't seem to work.

My comment looks like this (using both methods for sake of the example):

/**
 * blah blah blah
 * <p>
 * For example:
 * <pre>
 * {@code
 * {@literal @}begin_specification
 *  ...
 * &#64;end_specification
 * }
 * </pre>
 */

I can hit Run -> Generate Javadoc and everything runs fine with no errors but I see this when I look at the resulting output in a browser:

{@literal @}begin_specification
 ...
&#64;end_specification

Which isn't the desired result... Any suggestions/ideas?

I'm fairly new to Java but have used things like Doxygen in C/C++ in the past. Am I doing something wrong here? I'm using NetBeans 8.0 (Build 201403101706) with Java 1.8.0_05 x64.

回答1:

One way is to use:

<pre> <code>
   {@literal @}
</code> </pre>

instead of an {@code ...} block. See this example around line 86.

回答2:

This is a known bug. The link to the corresponding bug is:

https://bugs.openjdk.java.net/browse/JDK-8130754

As of 2016-10-07 there is no scheduled version for a fix.

回答3:

One way to get around this bug is to use a different character that looks similar to the standard "@" symbol. I found a few Unicode characters that are similar:

@ (U+0040): COMMERCIAL AT (the normal one that is broken)
ⓐ (U+24D0): CIRCLED LATIN SMALL LETTER A
﹫ (U+FE6B): SMALL COMMERCIAL AT
＠ (U+FF20): FULLWIDTH COMMERCIAL AT

I tried to write "@Override" with all these in a javadoc comment within a {@code ...} tag. (I use a Netbeans editor and a Mozilla Firefox browser.) All of the symbols worked except for #1 of course. Also, #3 did not show up in the editor, but it worked fine in the browser.

回答4:

I ran into this issue too with NetBeans 8.0.1 just now, so fiddled with it for about 15 minutes. At first with the {@code } formatter in the javadoc, nothing in the parens was showing up, so I had actual breaks in the text in the javadoc. Then after messing with it and changing it around (using <pre> and a couple of other tags) and opening other classes that has {@link } and whatnot, it just started working.

Not sure what was going on, but maybe the IDE's javadoc renderer needed some time to get fully "warmed up". As untechnical as that sounds, it really appeared that way. One javadoc header showed one {@code } block correctly, but not another one just a few words away. Now all are showing correctly though. Not sure this will help anyone, but after thinking I'd be sending a new bugzilla ticket to NetBeans, I'm back up and working. Back to my own tickets...

来源：https://stackoverflow.com/questions/23812761/trying-to-escape-the-symbol-in-a-code-block-within-a-javadoc-comment-with

标签

java

netbeans

escaping

javadoc

java-8