Exemple de code de ligne multiple dans le commentaire Javadoc

J'ai eu du mal à inclure un exemple de code spécifique dans un commentaire javadoc. J'aimerais partager celui-ci.
Veuillez noter ce qui suit:

• utilisation de l'ancienne <code> - tag pour empêcher l'interprétation des accolades
• l'utilisation de la "nouvelle" {@code ...} - tag pour obtenir les génériques inclus dans la sortie
• échappement du @ sign in @Override via "{@literal @}Override "car le générateur javadoc" s'incline " là-bas du fait que le @ va directement après une ouverture bouclée support
• supprimer un espace devant {@code et {@literal , pour compenser les espaces intérieurs et garder l'alignement

Code Javadoc:

/** this methods adds a specific translator from one type to another type. `
  * i.e.
  * <pre>
  * <code>new BeanTranslator.Builder()
  *   .translate(
  *     new{@code Translator<String, Integer>}(String.class, Integer.class){
  *      {@literal @}Override
  *       public Integer translate(String instance) {
  *         return Integer.valueOf(instance);
  *       }})
  *   .build();
  * </code>
  * </pre>
  * @param translator
  */

Est imprimé comme

new BeanTranslator.Builder()
  .translate(
    new Translator<String, Integer>(String.class, Integer.class){
      @Override
      public Integer translate(String instance) {
        return Integer.valueOf(instance);
      }})
  .build();

La source java a beaucoup de bons exemples pour cela. Voici un exemple de la tête de " Chaîne.java":

....
 * is equivalent to:
 * <p><blockquote><pre>
 *     char data[] = {'a', 'b', 'c'};
 *     String str = new String(data);
 * </pre></blockquote><p>
 * Here are some more examples of how strings can be used:
 * <p><blockquote><pre>
 *     System.out.println("abc");
 *     String cde = "cde";
 *     System.out.println("abc" + cde);
 *     String c = "abc".substring(2,3);
 *     String d = cde.substring(1, 2);
 * </pre></blockquote>
...

Joignez votre code multiligne avec des balises <pre></pre>.

Vous avez besoin des balises <pre></pre> pour les sauts de ligne, et du {@code ... } à l'intérieur pour les génériques. Mais alors il n'est pas permis de placer l'accolade d'ouverture sur la même ligne que la balise <generic>, car alors tout sera à nouveau affiché sur 1 ligne.

Affiche sur une ligne:

* ..
* <pre>
* {@code
* public List<Object> getObjects() {
*    return objects;
* }
* </pre>
* ..

Affiche avec des sauts de ligne:

* ..
* <pre>
* {@code
* public List<Object> getObjects() 
* {
*    return objects;
* }
* </pre>
* ..

Une autre chose étrange est que lorsque vous collez l'accolade de fermeture de {@code, elle s'affiche:

* ..
* <pre>
* {@code
*   public List<Object> getObjects() 
*   {
*     return objects;
*   }
* }
* </pre>
* ..

Sortie:

public List<Object> getObjects() 
{
   return objects;
}
}

/**
 * <blockquote><pre>
 * {@code
 * public Foo(final Class<?> klass) {
 *     super();
 *     this.klass = klass;
 * }
 * }
 * </pre></blockquote>
 **/

• <pre/> est requis pour préserver les lignes.
• {@code doit avoir sa propre ligne
• <blockquote/> est juste pour l'indentation.

public Foo(final Class<?> klass) {
    super();
    this.klass = klass;
}

Les exigences minimales pour Les codes appropriés sont <pre/> et {@code}.

/**
 * test.
 *
 * <pre>{@code
 * <T> void test(Class<? super T> type) {
 *     System.out.printf("hello, world\n");
 * }
 * }</pre>
 */

Donne

 <T> void test(Class<? super T> type) {
     System.out.printf("hello, world\n");
 }

Et un <blockquote/> environnant optionnel insère une indentation.

/**
 * test.
 *
 * <blockquote><pre>{@code
 * <T> void test(Class<? super T> type) {
 *     System.out.printf("hello, world\n");
 * }
 * }</pre></blockquote>
 */

Donne

     <T> void test(Class<? super T> type) {
         System.out.printf("hello, world\n");
     }

En insérant <p> ou en entourant <p> et </p> rendements avertissements.

J'ai pu générer de beaux fichiers HTML avec le snip suivant-il est montré dans le code 1.

 * <pre>
 * {@code
 * A-->B
 *  \
 *   C-->D
 *    \   \
 *     G   E-->F
 * }
 *</pre>

(Code 1)

Le code 1 s'est transformé en la page HTML javadoc générée dans la figure 1, comme prévu.

A-->B
 \
  C-->D
   \   \
    G   E-->F

(Fig. 1)

Cependant, dans NetBeans 7.2, si vous appuyez sur Alt+Shift+F (pour reformater le fichier actuel), le code 1 devient le code 2.

 * <
 * pre>
 * {@code
 * A-->B
 *  \
 *   C-->D
 *    \   \
 *     G   E-->F
 * }
 * </pre>

(Code 2)

Où le premier <pre> est maintenant divisé en deux lignes. Le code 2 produit le fichier HTML javadoc généré comme le montre la figure 2.

< pre> A-->B \ C-->D \ \ G E-->F

(Fig 2)

La suggestion de Steve B (Code 3) semble donner les meilleurs résultats et reste formatée comme prévu même après avoir appuyé sur Alt+Shift+F.

*<p><blockquote><pre>         
* A-->B
*  \
*   C-->D
*    \   \
*     G   E-->F
* </pre></blockquote>

(Code 3)

L'utilisation du code 3 produit la même sortie HTML javadoc que celle illustrée à la figure 1.

Il y a une différence significative entre <blockquote><pre>... et <pre>{@code.... Le premier omettra les déclarations de type dans les génériques mais le second les conservera.

E.g.: List<MyClass> myObject = null; s'affiche comme List myObject = null;, avec les deux premières et List<MyClass> myObject = null;, avec la seconde

Si vous êtes développeur Android, vous pouvez utiliser:

<pre class=”prettyprint”>

TODO:your code.

</pre>

Pour imprimer votre code en Javadoc avec du code Java.

Voici mes deux cents.

, Comme les autres réponses, déjà, vous devez utiliser <pre> </pre> en conjonction avec {@code }.

Utiliser pre et {@code}

• Encapsuler votre code dans <pre> et </pre> empêche votre code de s'effondrer sur une ligne;
• Emballage de votre code à l'intérieur {@code } empêche <, > et tout le reste de disparaître. Ceci est particulièrement utile lorsque votre code contient des génériques ou lambda expression.

Problèmes avec des annotations

Des problèmes peuvent survenir lorsque votre bloc de code contient une annotation. C'est probablement parce que lorsque le signe @ apparaît au début de la ligne Javadoc, il est considéré comme une balise Javadoc comme @param ou @return. Par exemple, ce code peut être mal analysé:

/**
 * Example usage:
 *
 * <pre>{@code
 * @Override
 * public void someOverriddenMethod() {

Le code ci-dessus disparaîtra complètement dans mon cas.

Pour résoudre ce problème, la ligne ne doit pas commencer par un @ signe:

/**
 * Example usage:
 *
 * <pre>{@code  @Override
 * public int someMethod() {
 *     return 13 + 37;
 * }
 * }</pre>
 */

Notez qu'il existe deux espaces entre les @code et @Override, pour garder les choses alignées avec les lignes suivantes. Dans mon cas (en utilisant Apache Netbeans), il est rendu correctement.

Essayez de remplacer "code" par "pre". La balise pre en HTML marque le texte comme préformaté et tous les linefeeds et espaces apparaîtront exactement comme vous les tapez.

Je viens de lire la référence Javadoc 1.5 ici, et seul le code avec < et > doit être enfermé dans {@code ...}. Voici un exemple simple:

 /** 
 * Bla bla bla, for example:
 *
 * <pre>
 * void X() {
 *    List{@code <String>} a = ...;
 *    ...
 * }
 * </pre>
 *
 * @param ...
 * @return ...
 */
 .... your code then goes here ...

Je joins mon exemple de code avec des balises <pre class="brush: java"></pre>et j'utilise SyntaxHighlighter pour les javadocs publiés. Cela ne fait pas de mal à l'E et rend les exemples de code publiés magnifiques.

En utilisant Java SE 1.6, il semble que tous les PRÉ-identifiants en MAJUSCULES soient le meilleur moyen de le faire dans Javadoc:

/**
 * <PRE>
 * insert code as you would anywhere else
 * </PRE>
 */

Est le moyen le plus simple de le faire.

Un exemple d'un javadoc que j'ai obtenu d'un java.awt.Méthode d'événement:

/**
 * <PRE>
 *    int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
 *    int offmask = CTRL_DOWN_MASK;
 *    if ((event.getModifiersEx() & (onmask | offmask)) == onmask) {
 *        ...
 *    }
 * </PRE>
 */

Cela produit une sortie qui ressemble exactement au code régulier, avec les espacements de code réguliers et les nouvelles lignes intactes.