10

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.

Community
  • 1
  • 1
TxAG98
  • 1,070
  • 2
  • 10
  • 25
  • There’s no sense in putting `@literal` in an `@code` block as `@code` already implies no processing of `@` inside. That’s what you see in your browser: exactly the contents of your `{@code …}` tag without any processing. So why do you think you need another `@literal`? – Holger May 22 '14 at 16:59
  • @Holger I don't think that's the case ("no processing of the @ inside"). – assylias May 22 '14 at 17:02
  • @assylias: I don’t get what you are trying to say. Within `{@code …}` there *is no processing* of `@`. That’s the purpose of `{@code …}`, so you can document code, e.g. annotations. *But line breaks can cause harm* within *inline*-tags… [Documentation:](http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#code) “Displays text in code font without interpreting the text as HTML markup or *nested javadoc tags*.” – Holger May 22 '14 at 17:06
  • Can't just use `@begin_specification` in the `{@code ...}` block. I get 2 errors, one on the `{@code` statement: `error: unterminated inline tag` and one on the `@begin_specification` line: `error: unknown tag: begin_specification`. So, inside the `{@code ...}` block it's still trying to process the @ symbol as a thing. – TxAG98 May 22 '14 at 17:07
  • @TxAG98: maybe you should *read* error messages: “unterminated inline tag” is as clear as possible. *inline* tag and *line break* does not fit very well together. – Holger May 22 '14 at 17:10
  • @Holger Ok, so how does `{@code ...}` go from being a valid multi-line code comment to a single line entry? Am I mistaken to believe that `{@code ...}` can be used to describe a multi-line code comment? If that's the case, is http://stackoverflow.com/questions/541920/multiple-line-code-example-in-javadoc-comment wrong? – TxAG98 May 22 '14 at 18:25
  • @TxAG98: If you look at the comments on the answer you see that other people had trouble with multi-line inline tags too. If don’t say, that the exposed behavior is correct, only that this combination is causing the trouble. Most probably, this javadoc implementation scans block tags first, splitting at every `@tag` placed at the beginning of a line and looks for inline tags within the blocks afterwards. If you escape the tag, everything will be treated as one block, but then, within the now-valid multi-line inline tag everything is treated as-is, producing `{@literal @}` and `@`. – Holger May 23 '14 at 08:10

4 Answers4

8

One way is to use:

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

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

assylias
  • 321,522
  • 82
  • 660
  • 783
6

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.

Ingo Kegel
  • 46,523
  • 10
  • 71
  • 102
  • While this link may answer the question, it is better to include the essential parts of the answer here and provide the link for reference. Link-only answers can become invalid if the linked page changes. - [From Review](/review/low-quality-posts/11046968) – bozzmob Jan 27 '16 at 14:30
  • Your templated answer and its bureaucratic spirit make me sad. That's what you get for helping people. – Ingo Kegel Jan 27 '16 at 20:54
  • It's not my templated answer ;) That's what Stackoverflow posts as a comment when I review. Not sure of who '-1' your answer. But, please include some text, it'll help. You know that! :) – bozzmob Jan 28 '16 at 03:36
  • It is a template and it is your comment. Why should more text help? The link references an issue in the JDK. It's not going to go away. If I copy some text from that bug report, how will that help anybody? What is your motivation in doing this kind of useless "review"? – Ingo Kegel Jan 28 '16 at 08:01
  • @IngoKegel I think you more closely consider the part "please add context around the link so your fellow users will have some idea what it is and why it’s there. Always quote the most relevant part of an important link, in case the target site is unreachable or goes permanently offline." It might also help to think of constructive feedback as something other than vigilanteism. –  Oct 07 '16 at 01:58
  • @toolbear Thanks for your concern and your friendly lecture. The details that you've added obfucscated the gist of the answer, so I've trimmed them a little. As you saw, the pertinent information in the bug report changes over time, so reproducing it in the answer will only makes things worse. Also, the JDK bug system will not go away - and if it every does, the question will become irrelevant. – Ingo Kegel Oct 07 '16 at 07:31
  • 1
    Note that using JDK 15.0.2 javadoc I no longer reproduce this issue/bug. I seem to be able to use @ without needing to escape it in javadoc `{@code ... }` multi-line. – Rob Bygrave Feb 26 '21 at 05:01
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:

  1. @ (U+0040): COMMERCIAL AT (the normal one that is broken)
  2. ⓐ (U+24D0): CIRCLED LATIN SMALL LETTER A
  3. ﹫ (U+FE6B): SMALL COMMERCIAL AT
  4. ＠ (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.

DBear
  • 312
  • 2
  • 9
  • 1
    This seems like a bad idea given that code blocks often serve as examples which downstream developers often cut/paste from. Would definitely be a footgun to see an `@` that isn't an `@`... – Lucas Apr 26 '23 at 21:04
1

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...

idclaar
  • 688
  • 2
  • 7
  • 17