In javaDoc, what's the best way of representing attributes in XML?

Question

When you're adding javaDoc comments to your code and you're outlining the structure of an XML document that you're passing back, what's the best way to represent attributes? Is there a best practice for this?

My general structure for my javaDoc comments is like this:

/**
 * ...
 * 
 * @return XML document in the form:
 * 
 * <pre>
 * &lt;ROOT_ELEMENT&gt;
 *    &lt;AN_ELEMENT&gt;
 *    &lt;MULTIPLE_ELEMENTS&gt;*
 * &lt;/ROOT_ELEMENT&gt;
 * </pre>
 */

Answer 1

Not sure I clearly understand your question.

My preferred solution would be to embed the schema XSD or DTC in the description of the return parameter. Your solution seems to lead to personal idioms on how to represent things like multiple elements or others. Using a standard like XSD or DTD allows you to have a well know and recognized language on how to describe the structure of a XML document.

Regarding the JavaDoc representation if you are using Eclipse you can specify under Save Actions to format your document. This way you can write normally with > and < and see it converted to the escaped HTML codes.

Answer 2

In the end, I just went with:

/**
 * ...
 * 
 * @return XML document in the form:
 * 
 * <pre>
 * &lt;ROOT_ELEMENT&gt;
 *    &lt;AN_ELEMENT attribute1 attribute2&gt;
 *    &lt;MULTIPLE_ELEMENTS&gt;*
 * &lt;/ROOT_ELEMENT&gt;
 * </pre>
 */