Question Exemple de code de ligne multiple dans le 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 code gèrerait les sauts de ligne. Quelle est la meilleure façon de formater des exemples de code dans les commentaires Javadoc?


464
2018-02-12 15:52


origine


Réponses:


En plus du déjà mentionné <pre> tags, vous devez également utiliser @code L'annotation JavaDoc, qui rendra la vie beaucoup plus facile 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>

Donne une sortie HTML correcte:

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

En omettant le @code bloquer (ou en utilisant un <code> tag) produira du HTML comme ceci:

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

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


670
2018-02-12 16:26



J'ai vraiment 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 vieux <code> - tag pour éviter que les accolades ne soient interprétées
  • utilisation de "nouveau" {@code ...} - tag pour obtenir les génériques inclus dans la sortie
  • échapper du signe @ @Override via "{@literal @}Override"parce que le générateur de javadoc" s'incline "là parce que le @ va directement après un support bouclé d'ouverture
  • enlever 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();

148
2017-11-22 12:13



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>
...

40
2018-02-12 15:59



Entourez votre code multiligne avec <pre></pre> Mots clés.


21
2018-02-12 15:56



Vous avez besoin de <pre></pre> étiquettes pour les sauts de ligne, et la {@code ... } à l'intérieur d'eux pour les génériques. Mais alors il n'est pas permis de placer l'accolade d'ouverture sur la même ligne que le <generic> tag, car alors tout sera à nouveau affiché sur une 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 lorsque vous collez l'accolade de fermeture de {@code, il s'affiche:

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

Sortie:

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

13
2017-08-04 12:35



/**
 * <blockquote><pre>
 * {@code
 * public Foo(final Class<?> klass) {
 *     super();
 *     this.klass = klass;
 * }
 * }
 * </pre></blockquote>
 **/
  • <pre/> est nécessaire 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;
}


MISE À JOUR avec JDK8

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

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

rendements

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

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


9
2018-03-05 10:14



J'ai été capable de 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 est devenu la page HTML javadoc générée dans la figure 1, comme prévu.

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

(Fig. 1)

Toutefois, dans NetBeans 7.2, si vous appuyez sur Alt + Maj + 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 cassé sur deux lignes. Le code 2 produit le fichier HTML javadoc généré, comme illustré à la figure 2.

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

(Figure 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 que celle illustrée à la figure 1.


4
2018-02-21 15:26



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 le conservera.

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


3
2017-07-19 09:24



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

<pre class=”prettyprint”>

TODO:your code.

</pre>

Pour imprimer votre code dans Javadoc avec du code Java.


2
2017-08-29 09:02



Essayez de remplacer "code" par "pré". La balise pre en HTML marque le texte comme étant préformaté et tous les sauts de ligne et les espaces apparaissent exactement comme vous les tapez.


1
2018-02-12 15:58