web-dev-qa-db-fra.com

Exemple de code de ligne multiple dans un commentaire Javadoc

J'ai un petit exemple de code à 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 affiché dans la Javadoc ne comporte pas de saut de ligne rendant la lecture difficile.

-- 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 l’étiquette de code gère les sauts de ligne. Quel est le meilleur moyen de formater des exemples de code dans les commentaires Javadoc?

javahtmljavadoc
508
Mark

Outre les balises <pre> déjà mentionnées, vous devez également utiliser l'annotation @code JavaDoc, qui simplifiera beaucoup la vie en ce qui concerne les problèmes liés aux entités HTML (en particulier avec Generics), 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 bloc @code (ou en utilisant une balise <code>], le code HTML sera le suivant:

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

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

720
Fabian Steeg

J'ai eu beaucoup de difficulté à inclure un exemple de code spécifique dans un commentaire javadoc. Je voudrais partager celui-ci.
Veuillez noter les points suivants:

  • utilisation de l'ancien _<code>_ - balise pour empêcher l'interprétation des accolades
  • utilisation de "nouveau" _{@code ...}_ - balise pour obtenir les génériques inclus dans la sortie
  • échappe du @ sign in _@Override_ via "_{@literal @}Override_" car le générateur javadoc "bascule" à cet endroit car le @ passe directement après une accolade ouvrante
  • supprimez un espace devant _{@code_ et _{@literal_, pour compenser les espaces intérieurs et conserver 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();
_
159
Christoph Naber

La source Java contient de nombreux bons exemples à cet égard. Voici un exemple tiré 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>
...
41
Steve B.

Placez votre code multiligne avec les balises <pre></pre>.

24
Zach Scrivena

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 est interdit de placer l'accolade ouvrante sur la même ligne que la balise <generic>, car 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 que lorsque vous collez l'accolade fermante de {@code, elle s'affiche:

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

Sortie:

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

J'ai été capable de générer de beaux fichiers HTML avec le snip-it suivant affiché 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 sur 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 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 génère le 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 que celle illustrée à la figure 1.

4
bitsdanceforme

Voici mes deux cents.

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

Utilisez pre et _{@code}_

  • Insérer votre code dans _<pre>_ et _</pre>_ empêche votre code de s’effondrer sur une seule ligne;
  • Envelopper votre code dans _{@code_ _}_ empêche _<_, _>_ et tout ce qui se trouve entre les deux 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. Cela est probablement dû au fait que lorsque le signe _@_ apparaît au début de la ligne Javadoc, il est considéré comme une balise Javadoc du type _@param_ ou _@return_. Par exemple, ce code pourrait être analysé incorrectement:

_/**
 * 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 _@code_ et _@Override_, pour que les éléments restent alignés sur les lignes suivantes. Dans mon cas (avec Apache Netbeans), le rendu est correct.

3
MC Emperor

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; s'affiche sous la forme List myObject = null; avec les premiers et de List<MyClass> myObject = null; avec le second.

3
Tamas

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

<pre class=”prettyprint”>

TODO:your code.

</pre>

Pour imprimer votre code dans Javadoc avec le code Java.

2
ifeegoo

Essayez de remplacer "code" par "pre". La balise pre en HTML marque le texte comme étant préformaté et tous les sauts de ligne et les espaces apparaîtront exactement au fur et à mesure que vous les tapez.

1
Edwin

Je viens de lire la référence Javadoc 1.5 ici , et seul le code avec <et > doit être placé à l'intérieur de {@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 ...
1
mljrg

En utilisant Java SE 1.6, il semble que tous les identifiants UPPERCASE PRE soient le meilleur moyen de le faire en 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 standard, avec les espacements de code normaux et les nouvelles lignes intactes.

0
Eugene_CD-adapco

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

0
Jarek Przygódzki