Does Javadoc have an equivalent to <![CDATA[ … ]]>?

Question

Unfortunately, there is no CDATA in HTML.

This is a pity, because it would be perfect for adding javadoc comments that include XML, so you don\'t have t

Answer 1

I have tried quite a few solutions, none of which were very satisfactory for my needs. Doing the pre + @code (or @literal) tags will usually work:

 <pre>
 {@literal
 <configFiles>
   <configFile>
     <type>LOGICAL_INDEX_CONFIG</type>
   </configFile>
 </configFiles>}
 </pre>

The trouble is, what if you have ${dollar_sign_variables} in your html? (and this is frequent if your documentation uses xml examples which rely on maven filtering). Say you have ${ITEM_INDEX_TO_LOGICAL}, Eclipse will render it like this:

<configFiles>
  <configFile>
     ITEM_INDEX_TO_LOGICAL

   }

Ultimately, I had no choice but to stick to the html-escaping method (you can use this one) to get it to render propertly:

This:

 <configFiles>
   <configFile>
     <type>${ITEM_INDEX_TO_LOGICAL}</type>
   </configFile>
 </configFiles>

Renders like this:

 </configFiles>
   <configFile>
     <type>${ITEM_INDEX_TO_LOGICAL}</type>
   </configFile>
 </configFiles>

This will unfortunately put you into a position where you can't really understand the 'example xml' being documented unless you render the Javadoc. Fortunately eclipse can do this for you on the fly...

Answer 2

Extending @Fabian's answer, I use both <pre> and {@code ...}. Here an example with XML as source code:

/*Outputs data from a result set to an XML
 * with following structure:
 * <pre>
 * {@code
 * <row>
 *  <FIELD1>gregh</FIELD1>
 *  <FIELD2>487</FIELD2>
 *  <!-- etc. -->
 * </row>
 * <!-- more rows-->
 * }
 * </pre>
 */

<pre> allows you to write code on multiple lines and preserve its structure.

Tested with Eclipse 3.6.1.

Answer 3

You can use JavaDoc's @code tag: /** This parses {@code <complexType name="">} */

Answer 4

Close and reopen the {@code} tag around the braces to get ${dollar_sign_variables} to render correctly in eclipse despite bug 206319 and bug 206345 and without resorting to full HTML escaping:

/*
 * <pre>
 * {@code
 * <outer>
 *   <inner1>Text</inner1>
 *   <inner2>$}{ "script" }{@code </inner2>
 * </outer>
 * }
 * </pre>
 */

which renders in Eclipse Indigo SR2 (3.7.2) as

<outer>
  <inner1>Text</inner1>
  <inner2>${ "script" }</inner2>
</outer>