Exemple de code de plusieurs lignes dans un commentaire Javadoc

J'ai un petit exemple de code que je veux inclure dans le commentaire Javadoc pour une méthode.

/**
 * -- ex: looping through List of Map objects --
 * <code>
 * for (int i = 0; i < list.size(); i++) {
 *      Map map = (Map)list.get(i);
 *      System.out.println(map.get("wordID"));
 *      System.out.println(map.get("word"));
 * }
 * </code>
 * 
 * @param query - select statement
 * @return List of Map objects
 */

Le problème est que l'exemple de code apparaît dans le Javadoc sans saut de ligne, ce qui le rend difficile à lire.

-- ex: looping through List of Map objects -- for (int i = 0; i list.size(); i++) { Map map = (Map)list.get(i); System.out.println(map.get("wordID")); System.out.println(map.get("word")); } 
Parameters
query - - select statement 
Returns:
List of Map objects 

Je suppose que je me trompe en supposant que la balise de code gérerait les sauts de ligne. Quelle est la meilleure façon de formater des exemples de code dans les commentaires Javadoc?

En plus des <pre>balises déjà mentionnées , vous devez également utiliser l' @codeannotation JavaDoc, qui vous facilitera la vie en ce qui concerne les problèmes d'entités HTML (en particulier avec les génériques), par exemple:

* <pre>
* {@code
* Set<String> s;
* System.out.println(s);
* }
* </pre>

Donnera une sortie HTML correcte:

Set<String> s;
System.out.println(s);

En omettant le @codebloc (ou en utilisant une <code>balise), le code HTML ressemblera à ceci:

Set s;
System.out.println(s);

(Pour référence, les descriptions des balises Java SE 8 peuvent être trouvées ici: balises Javadoc )

J'ai eu beaucoup de 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>balise pour empêcher l'interprétation des accolades
• utilisation de la {@code ...}balise "new" pour obtenir les génériques inclus dans la sortie
• échappement du signe @ @Overridevia " {@literal @}Override" car le générateur javadoc "s'incline" car le @ va directement après une accolade ouvrante
• supprimer un espace devant {@codeet {@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é en tant que

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 "String.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 <pre></pre>balises.

Vous avez besoin des <pre></pre>balises pour les sauts de ligne et de l' {@code ... }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 <generic>balise, car alors tout sera à nouveau affiché sur 1 ligne.

Affiche sur une seule 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>
* ..

Production:

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

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

• <pre/> est nécessaire pour conserver 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>
 */

les rendements

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

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

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

les rendements

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

Insérer <p>ou entourer avec <p>et </p>donne des avertissements.

J'ai pu générer de beaux fichiers HTML avec le snip-it suivant 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 + Maj + F (pour reformater le fichier actuel), le code 1 se transforme en 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 un fichier HTML javadoc généré, comme illustré à 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 + Maj + 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 comme indiqué sur la figure 1.

Voici mes deux cents.

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

Utiliser preet{@code}

• Envelopper votre code à l'intérieur <pre>et </pre>empêche votre code de s'effondrer sur une seule ligne;
• Enroulant 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 expressions génériques ou lambda.

Problèmes avec les 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 @paramou @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 y a deux espaces entre @codeet @Override, pour garder les choses alignées avec les lignes suivantes. Dans mon cas (en utilisant Apache Netbeans), il est rendu correctement.

Il existe une différence significative entre <blockquote><pre>...et <pre>{@code....La première omettra les déclarations de type dans les génériques, mais la seconde les conservera.

E.g.: List<MyClass> myObject = null; affiche comme List myObject = null;avec les premiers et comme List<MyClass> myObject = null;avec le second

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.

Essayez de remplacer "code" par "pré". La balise pré en HTML marque le texte comme étant préformaté et tous les sauts de ligne et les 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 inclus à l'intérieur {@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 ...

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

En utilisant Java SE 1.6, il semble que tous les identifiants UPPERCASE PRE 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'une méthode java.awt.Event:

/**
 * <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 normal, avec les espacements de code réguliers et les nouvelles lignes intacts.

Dans Visual Studio Code au moins, vous pouvez forcer un commentaire Javadoc à respecter les sauts de ligne en les encapsulant dans des triplets, comme indiqué ci-dessous:

/** ```markdown
 * This content is rendered in (partial) markdown.
 * 
 * For example, *italic* and **bold** text works, but [links](https://www.google.com) do not.
 * Bonus: it keeps single line-breaks, as seen between this line and the previous.
 ``` */