How do I write a block comment in my javadoc example?

Question

So I have a javadoc that looks like this (censored for the public of course):

/**
 * Description of my method
 * <p>
 * <b>Example:</b>
 * </p>
 * <pre>
 * {@code
 * /**
 *  * Sample Javadoc
 *  *&#47;
 *  public final void testMyMethod()
 *  &#123;
 *      // some logic
 * &#125;}
 * </pre>
 * @return Description of my return value.
 */

So the reason for this is that doing */ in my example will end the javadoc. Having the braces confuses the @code tag.

The problem is that the generated javadoc shows the HTML entities codes instead of the actual character that I want to display to the consumers of my javadoc. Any ideas on how I can get around this?

Answer 1

There's no real way to do this unfortunately (at least not that I know of.) I've been stung by this in the past and it's really rather annoying!

The two workarounds (neither is great) that sort-of get the right approach are:

• Closing and reopening the code tag to exclude the annoying characters (so doing }/{@code)

• Ditching {@code altogether and just using the old fashioned <code> tags.

Personally I'd favour the last approach because it's a bit neater and (presumably) easier to convert later if a fix ever arrives - but it's not ideal.