Exemple de code de plusieurs lignes dans un commentaire Javadoc


531

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?

Réponses:


743

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 )


63
Je l'aurais pensé aussi, mais malheureusement ce n'est pas le cas, vous devez toujours ajouter la balise <pre> pour obtenir des sauts de ligne.
Fabian Steeg, le

12
Malheureusement, il semble que lorsque vous appuyez sur ctrl + shift + F (Format du code dans Eclipse), Eclipse gâche la balise {@code} et la remplace par {& # 064; code ...
jpdaigle

3
@jpdaigle Je viens d'essayer ceci dans Eclipse Galileo et Helios et le formateur ne remplace rien pour moi (sur Mac OS, mais je n'ai jamais vu le formateur faire quoi que ce soit sur d'autres plates-formes non plus).
Fabian Steeg

30
Un autre malheur, si vous avez des blocs dans votre exemple de code utilisant des accolades "{}", la première accolade fermante terminera le bloc @code. Une solution consiste à utiliser (attendez ...) des entités html pour les accolades. Je ne vois pas d'argument convaincant pour les balises <pre> pour le code avec des blocs.
Ed Griebel

2
Eclipse gâche la balise {@code} et la remplace par le code {& # 064; - Ce n'est pas à cause d'Eclipse, c'est à cause de l'utilitaire javadoc (buggé?). Si vous avez un caractère @ dans le code multiligne à l'intérieur de {@code ... multiline ...}, javadoc ne parvient pas à l'analyser correctement :( C'est du moins ce que je vois avec l'implémentation javadoc d'Oracle JDK1.7.0_45.
Homme

167

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();

2
Cela fonctionne mais je reçois un avertissement lors de l'exécution de javadoc produisant cet avertissement "avertissement: {@code} dans <code>"
Shane Rowatt

3
C'est celle qui a fonctionné, la réponse acceptée ne fonctionne pas bien dans mon éclipse (4.6.2).
Eric Wang

Je me demande pourquoi tout cela est nécessaire, mon intellij 13 et versions ultérieures fonctionnent très bien avec le code dans la réponse acceptée. Est-ce juste un problème d'éclipse?
bvdb

Oui, j'ai également vu ce travail très bien dans IntelliJ 11 et versions ultérieures. IntelliJ le gère correctement. Malheureusement, Eclipse ne rend PAS correctement le JavaDoc (état de survol) et ignore à la fois les nouvelles lignes et les sauts html. J'essaie de trouver une solution qui fonctionne bien dans les deux IDE, car ils sont deux des meilleurs IDE utilisés aujourd'hui.
Michael M

41

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

9
En résumé,<pre><blockquote>...</blockquote></pre>
Jin Kwon

6
Plutôt<p><blockquote><pre> </pre></blockquote></p>
masterxilo

@JinKwon malheureusement, cela ne fonctionne pas toujours, pas dans mon extrait de code :( l'ajout d'un {@code au début fonctionne, même si la fermeture} ne sera pas atteinte
benez

Cela semble fonctionner pour la plupart du code, mais n'échappe pas aux crochets angulaires comme dans List<String>. Pour cela, j'utilise <pre>{@code ... }</pre>.
Daniel


14

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;
}
}

4
Bienvenue sur Stack Overflow. Pour formater le code dans les publications, vous pouvez soit le préfixer (sur un paragraphe séparé) de quatre espaces, soit les entourer de backticks (`` ...``). Vous n'avez pas besoin <code>et les <pre>mots clés. J'ai édité votre réponse dans cet esprit.
Paŭlo Ebermann

10
/**
 * <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;
}


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

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.


5

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.


4

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.


3

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


2

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.


1
Veuillez expliquer: qu'est-ce qui, dans les outils Android, devrait faire fonctionner cela, compte tenu des problèmes qui nécessitent la balise @code? Et quel composant devrait définir la classe prettyprint? Android utilise Javadoc normal.
noamtm

Xamarin / VS, Android Studio, ou cela n'a-t-il pas d'importance?
tyblu

@tyblu Android Studio fonctionne, mais Xamarin Studio / VS peut ne pas fonctionner. Vous pouvez essayer.
ifeegoo

1

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.


1

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

0

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.



Avec Syntax Highlighter, vous devez charger le script et corriger le CSS. Semble incroyable, mais vous devez mettre le chemin d'accès correct aux scripts et css requis. De plus, si vous souhaitez utiliser hors ligne, vous devez faire attention aux bons chemins.
Alex Byrth

0

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.


2
Cela n'ajoute rien aux réponses existantes.
madth3

madth3, vous avez raison. Je pensais avoir vu une différence lors de l'utilisation de pré-modificateurs inférieurs par rapport à UPPERCASE, mais au deuxième regard, cela ne semble pas être le cas. Cela pourrait également avoir quelque chose à voir avec la façon dont il est apparu sur cette page Web par rapport à la façon dont il apparaît dans javadoc.
Eugene_CD-adapco

1
sensible à la casse dans la balise html?
Jasonw

0

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.
 ``` */
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.