I’m not sure how I’ve never run into this, but I recently noticed that writing XML in Javadoc results in it not being rendered correctly.

As an example, let’s take a look at Betaville’s Collada exporter and what its Javadoc looks like when viewed

/**
 * Exporter for COLLADA files
 *
 * <COLLADA>
 * 	<asset/>
 * 	<library_cameras/> // not important
 * 	<library_lights/> // not important
 * 	<library_images/>
 * 	<library_effects/>
 * 	<library_materials/>
 * 	<library_geometries/>
 * 	<library_animations/>
 * 	<library_controllers/>
 * 	<library_visual_scenes/>
 * 	<scene/>
 *
 * @author Skye Book
 * @experimental - incomplete
 *
 */

No @code tags means bad news

Gross!!!  What happened?  After some digging, I found that it is necessary to wrap the documentation in question with the code tag using {@code someCodeHere}.  But the fun doesn’t end there, if you want to do something akin to an XML structure, you must wrap each line with the code tag as follows.

/**
 * Exporter for COLLADA files
 * <p>
 *
 * {@code<COLLADA>}</br>
 * 	{@code<asset/>}</br>
 * 	{@code<library_cameras/> // not important}</br>
 * 	{@code<library_lights/> // not important}</br>
 * 	{@code<library_images/>}</br>
 * 	{@code<library_effects/>}</br>
 * 	{@code<library_materials/>}</br>
 * 	{@code<library_geometries/>}</br>
 * 	{@code<library_animations/>}</br>
 * 	{@code<library_controllers/>}</br>
 * 	{@code<library_visual_scenes/>}</br>
 * 	{@code<scene/>}</br>
 *
 * @author Skye Book
 * @experimental - incomplete
 *
 */

So nice!

Well with that sorted I guess there’s no more excuse for poor documentation, eh?