Comment citer "*/" dans les JavaDocs ?

Question

J'ai besoin d'inclure */ dans mon commentaire sur JavaDoc. Le problème est que c'est également la même séquence pour fermer un commentaire. Quelle est la bonne façon de citer/échapper cette séquence ?

Exemple :

/**
 * Returns true if the specified string contains "*/".
 */
public boolean containsSpecialSequence(String str)

Suivi : Il semble que je puisse utiliser / pour la barre oblique. Le seul inconvénient est que ce n'est pas très lisible lorsqu'on visualise le code directement dans un éditeur de texte.

/**
 * Returns true if the specified string contains "*/".
 */

Answer 1

Utilisez l'échappement HTML.

Donc, dans votre exemple :

/**
 * Returns true if the specified string contains "*/".
 */
public boolean containsSpecialSequence(String str)

/ s'échappe comme un caractère "/".

Javadoc devrait insérer la séquence échappée sans la modifier dans le HTML qu'il génère, et cela devrait se traduire par "*/" dans votre navigateur.

Si vous voulez être très prudent, vous pouvez échapper aux deux personnages : */ se traduit par */

Editar:

Suivi : Il semble que je puisse utiliser / pour la barre oblique. Le seul inconvénient est que ce n'est pas très lisible lorsque l'on visualiser le code directement.

Alors ? Le but n'est pas que votre code soit lisible, le but est que votre code documentation pour être lisible. La plupart des commentaires Javadoc intègrent du HTML complexe pour l'explication. L'équivalent du C# offre une bibliothèque complète de balises XML. J'ai vu des structures assez complexes là-dedans, laissez-moi vous le dire.

Edit 2 : Si cela vous dérange trop, vous pouvez intégrer un commentaire en ligne non-javadoc qui explique l'encodage :

/**
 * Returns true if the specified string contains "*/".
 */
// returns true if the specified string contains "*/"
public boolean containsSpecialSequence(String str)

Answer 2

/**
 * Returns true if the specified string contains "*/".
 */

Il s'agit de la "bonne" solution, mais pour des raisons de lisibilité, j'opterais plutôt pour.. :

/**
 * Returns true if the string contains an asterisk followed by slash.
 */

Answer 3

Utiliser l'entité

*/ 

Dans votre documentation, il apparaîtra sous la forme d'un "*/".

Answer 4

Je vous suggère également d'ajouter une ligne de commentaire quelque part à proximité disant quelque chose comme

// */ is html for */

Answer 5

Une autre solution que j'ai trouvée par hasard, juste pour être complet : ajouter des balises HTML qui ne modifient pas la sortie entre * et /.

  /**
   * *<b/>/
   */

Comparée à la solution d'échappement HTML, cette solution semble être un affreux bidouillage, mais elle donne également le bon résultat en sortie HTML.