Does Javadoc have an equivalent to ?

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 to escape the < and >, for example:

/**<![CDATA[ This parses <complexType name=""> ]]>*/

However, it would be possible for javadoc to recognize the CDATA section, and convert it to HTML for you. For example:

This parses &lt;complexType name=""&gt;

Or it could use some simpler syntax than CDATA. Because javadoc is extensible, it's possible someone has added this functionality; or maybe javadoc already has it buried somewhere inside... Does anybody know?

score 46 · Accepted Answer · answered Nov 23 '09 at 09:41

46

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

answered Nov 23 '09 at 09:41

Fabian Steeg

44,988
7
85
112

4

+1 Note that {@code ... } can span multiple lines. eclipse will claim it's an error, but it's not. It also does brace-counting! So you can use curlies in your actual code snippet, as long as they match up. – Kevin Bourrillion Nov 23 '09 at 19:06
I'm seeing IDEA process a multi-line `{@code}` block by folding the lines together, which one won't suffer with `
```
`. That's sad, as `{@code}` sounded like a nice solution to not having to escape the opening carets.
```
– seh Jan 13 '11 at 15:52

score 34 · Answer 2 · edited May 23 '17 at 12:32

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.

score 8 · Answer 3 · answered Sep 26 '12 at 14:06

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>

score 4 · Answer 4 · answered Jun 06 '12 at 07:49

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:

 &lt;configFiles&gt;
   &lt;configFile&gt;
     &lt;type&gt;${ITEM_INDEX_TO_LOGICAL}&lt;/type&gt;
   &lt;/configFile&gt;
 &lt;/configFiles&gt;

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

Does Javadoc have an equivalent to ?

4 Answers4

Linked