Alex Rivera | Logout

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

Asked 2009-11-23T09:33:14.387
29

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?

java html xml javadoc cdata
Edit
Report

1 Answer

4

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

answered 2012-06-06T07:49:44.357

Your Answer