Dans javaDoc, quelle est la meilleure façon de représenter les attributs en XML?

Question

Lorsque vous ajoutez des commentaires javaDoc à votre code et que vous décrivez la structure d'un document XML que vous transmettez, quelle est la meilleure façon de représenter les attributs? Y a-t-il une meilleure pratique pour cela?

Ma structure générale pour mon Javadoc commentaires est comme ceci:

/** 
* ... 
* 
* @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

Je ne sais pas, je comprends bien votre question.

Ma solution préférée serait d'intégrer le schéma XSD ou DTC dans la description du paramètre de retour. Votre solution semble conduire à des idiomes personnels sur la façon de représenter des choses comme des éléments multiples ou d'autres. L'utilisation d'un standard comme XSD ou DTD vous permet d'avoir un langage bien connu et reconnu sur la façon de décrire la structure d'un document XML.

En ce qui concerne la représentation JavaDoc si vous utilisez Eclipse, vous pouvez spécifier sous Enregistrer les actions pour formater votre document. De cette façon, vous pouvez écrire normalement avec > et < et le voir converti en codes HTML échappés.

Answer 2

En fin de compte, je suis allé avec tout:

/** 
* ... 
* 
* @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> 
*/