Escape '@' in code blocks

[ctrimble]

When creating a code block, '@' characters should be translated into {@literal @}, so they are not interpreted as javadoc tags.

[Abnaxos]

Unfortunately, this is not possible the way the doclet is currently implemented. JavaDoc will start the tag block as soon as it encounters a leading '@'.

I thought about this before, my idea back then was to add the shortcut {@} which would be expanded to {@literal @}.

I could also use getRawCommentText() instead of getDocComment(), getTags() etc. However, this would mean that I'd have to parse the whole comment text myself. That's not too difficult because the structure of the comment text is rather easy, but is it really worth the trouble?

[ctrimble]

I can't say if it is worth the trouble, but one of the first things I tried to do was place annotated java code in my javadocs. Having to escape anything in the code block seems counter intuitive.

[obfischer]

This issue is a show stopper for me. I wanted to add some code example on the usage of the annotations of my library. And therefore I need the @ sign.

Isn't it a possible solution to use HTML entities as &#64A; for @? The parser could pass this entities directly to the output.

[wherget]

I just ran into this as well. What's the current best practice for code examples that involve annotations? (He asks, slightly hoping for something other than "Don't write them.")

[Abnaxos]

Currently, you'll still have to escape them manually: Use the HTML entity or, a bit more readable: Use {@literal @}.

Not, however, that if I find a proper solution to this, you might end up with code samples that contain literally {@literal @}.

[plamentotev]

What about something like this:

 /**
  * A simple javadoc comment.
  *
  * ```java
  . @annotation
  . public void method() {
  .
  . }
  * ```
  */

This would avoid the problem with the @ character - because it's not the first symbol on the line it's no longer parsed as tag. And we only need to instruct pegdown to strip the leading dots in code fence blocks.

Of course any character will do (well except @ :smile:), but I think the dot is the closest in appearance to *, so the combination of . and * will not distract the reader as much as other combinations will.

[tombensve]

I just tried {@literal @} but that generates a space before the @ which makes the code block look strange when the annotation is indented:

 @SomeAnnotation
public void someMethod() {
    ...
}

[dautelle]

Best solution I found: Use an invisible whitespace character in front of the @ (http://www.somebits.com/weblog/tech/zero-width-space.html)

[Abnaxos]

The solution coming up (it's in master) is using '.'. It's not "escapeless", because that is not possible: It must also work with IDEs and any IDE will stumble on this. Javadoc specfies that an '@' at the beginning of a line introduces the tag block, full stop.

To be more specific:

.@MyAnnotation

will then render as

@MyAnnotation // no additional space, really

If you really mean ".@", add an additional dot:

..@MyAnnotation

renders as

.@MyAnnotation

and so forth.

This notation will only apply to the exact regex "^\s*.+@" (after removing the leading asterisk) and reduce the dots by one (spaces are preserved). It's still a compromise, but I think, it's a good one, because it's rather discrete.

Then again, writing this … I'll have to look into @plamentotev's idea again. That could actually be a very elegant solution:

/**
 * text
 *
 |-- java
 | @MyAnnotation
 */

as an third alternative to code blocks. I now have the tools to make this work.