Adding XML to Javadoc comments

Steve Neal Development, Java Programming 7 Comments

In this article I’ll show you a simple technique for inserting XML code snippets in your Javadocs that keeps them readable in both the source code and the resulting HTML files.

Problems with adding comments

Inserting code snippets into Javadoc comments that read well in both the source code and the HTML files produced by Javadoc can be a very fiddly process. Inserting XML snippets into your documentation can make this trickier still. Read on to discover a simple technique that works equally well with both Java and XML code snippets in your Javadocs.

I recently needed to add some comments to my Java classes to show some simple cases of how they should be used in other applications.

In particuar, the classes I was developing were for use in Spring based applications and would need to be configured using XML. This is where the Javadoc tool really starts to struggle. When generating the HTML pages, Javadoc does not (by default) escape the XML characters it finds in your comments – it just copies them verbatim into the HTML it produces.

So, if you were to write a comment like this:

/**
* <p>This class should be used as follows:</p>
* <bean>
*     <property name="propName" value="propValue"/>
* </bean>
*/
public class MockObject {
...
}

you will only see the following when examining the resulting Javadocs in a browser:

This class should be used as follows:

The reason for this is that the markup has been copied directly into the HTML page. The browser doesn’t recognise the bean tag and simply ignores it.

Using the {@code … } Javadoc tag

Javadoc does provide a useful tag or adding code to comments:

/**
* <p>This class should be used as follows:</p>
* {@code
* <bean>
*     <property name="propName" value="propValue"/>
* </bean>
* }
*/
public class MockObject {
...
}

This will cause the XML within the {@code … } markup to be escaped so that the < and > characters are displayed properly. The problem with this technique though is that line breaks will be ignored by the browser and all the neatly formatted XML in our source code will be displayed on a single line by a browser.

Preserving XML Characters and Line Breaks

In order to preserve the line breaks and the XML characters, you need to use the {@code … } Javadoc tags in conjunction with HTML pre tags:

/**
* <p>This class should be used as follows:</p>
* <pre>
* {@code
* <bean>
*     <property name="propName" value="propValue"/>
* </bean>
* }
* </pre>
*/
public class MockObject {
...
}

This will produce the kind of markup we’re looking for:

This class should be used as follows:

<bean>
     <property name="propName" value="propValue"/>
</bean>

The HTML pre tags instruct the browser to respect whitespace characters and to show the spaces and line breaks. The {@code … } Javadoc tag instructs the Javadoc tool to escape the < and > characters so that they will also be displayed correctly by the browser too.

So there you have it! A (relatively) simple technique that allows both Java and XML code snippets to look as good in your Java source code as they do in the Javadoc HTML files.

Comments 7

  1. paul_lance

    Thanks for this – I’ve been looking for a way to do this for ages.

    You’d think something this essential would be much simpler to do though :-)

  2. Karol Zielonko

    Thanks for the info. I’ve used this successfully as you layed out in JBuilder 2007. Two comments.

    1) The closing “pre” tag should be “</pre>” not “<pre>”
    2) In JBuilder 2007 I found its code formatting (as I had it set up) was changing double quotes to " and the " was appearing directly in the HTML. To fix this you do Java->Preferences->Java->Code Style->Formatter. Then select the profile you’re using and hit Edit. Then select the Comments tag and uncheck “Format Java code snippets”

  3. Ojitha Kumanayaka

    This is great. I had a big problem of doing. Thse simple things are sometime very difficult to acheieve. Thank you very much

  4. MichZem

    Thank you so much. Regularly, I’m fighting with my javadoc for formatting a simple line so it will look nice. It’s the first time I saw your old post (2 years already!!!) .
    Thanks you!

Leave a Reply

Your email address will not be published. Required fields are marked *