Ejemplo de código de línea múltiple en comentario Javadoc

Tengo un pequeño ejemplo de código que quiero incluir en el comentario Javadoc para un método.

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

El problema es que el ejemplo de código aparece en el Javadoc sin saltos de línea, lo que dificulta su lectura.

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

Supongo que me equivoco al suponer que la etiqueta de código manejaría los saltos de línea. ¿Cuál es la mejor manera de formatear ejemplos de código en comentarios Javadoc?

Además de las <pre>etiquetas ya mencionadas , también debe usar la @codeanotación JavaDoc, que hará la vida mucho más fácil cuando se trata de problemas de entidades HTML (en particular con genéricos), por ejemplo:

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

Dará salida HTML correcta:

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

Si se omite el @codebloque (o se usa una <code>etiqueta), se generará HTML como este:

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

(Para referencia, las descripciones de las etiquetas Java SE 8 se pueden encontrar aquí: Etiquetas Javadoc )

Tuve un momento realmente difícil al incluir un ejemplo de código específico en un comentario de javadoc. Me gustaría compartir este.
Tenga en cuenta lo siguiente:

• uso de <code>etiquetas antiguas para evitar que se interpreten los corchetes
• uso de "nuevo" {@code ...}- etiqueta para obtener los genéricos incluidos en la salida
• escapar del inicio de sesión @ a @Overridetravés de " {@literal @}Override" porque el generador javadoc "se inclina" allí debido al hecho de que el @ va directamente después de una llave de apertura
• eliminar un espacio delante de {@codey {@literal, para compensar los espacios interiores y mantener la alineación

código 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
  */

se imprime como

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

La fuente de Java tiene muchos buenos ejemplos de esto. Aquí hay un ejemplo del jefe 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>
...

Adjunte su código multilínea con <pre></pre>etiquetas.

Necesita las <pre></pre>etiquetas para los saltos de línea y el {@code ... }interior para los genéricos. Pero entonces no está permitido colocar la llave de apertura en la misma línea que la <generic>etiqueta, porque entonces todo se mostrará en 1 línea nuevamente.

Muestra en una línea:

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

Pantallas con saltos de línea:

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

Otra cosa extraña es que cuando pegas la llave de cierre {@code, se muestra:

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

Salida:

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

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

• <pre/> se requiere para preservar líneas.
• {@code debe tener su propia línea
• <blockquote/> es solo por sangrado.

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

Los requisitos mínimos para los códigos adecuados son <pre/>y {@code}.

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

rendimientos

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

Y un entorno opcional <blockquote/>inserta una sangría.

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

rendimientos

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

Insertar <p>o rodear <p>y </p>generar advertencias.

Pude generar archivos HTML atractivos con el siguiente fragmento que se muestra en el Código 1.

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

(Código 1)

El código 1 se convirtió en la página HTML javadoc generada en la Fig. 1, como se esperaba.

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

(Figura 1)

Sin embargo, en NetBeans 7.2, si presiona Alt + Shift + F (para formatear el archivo actual), el Código 1 se convierte en el Código 2.

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

(Código 2)

donde el primero <pre>ahora se divide en dos líneas. El código 2 produce el archivo HTML javadoc generado como se muestra en la figura 2.

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

(Figura 2)

La sugerencia de Steve B (Código 3) parece dar los mejores resultados y permanece formateada como se esperaba incluso después de presionar Alt + Shift + F.

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

(Código 3)

El uso del Código 3 produce la misma salida HTML de javadoc como se muestra en la Fig. 1.

Aquí están mis dos centavos.

Como ya dicen las otras respuestas, debe usarlas <pre> </pre>en conjunción con {@code }.

Uso prey{@code}

• Envolviendo su código dentro <pre>y </pre>evita que su código se colapse en una línea;
• Envolver el código dentro {@code }previene <, >y todo en el medio de desaparecer. Esto es particularmente útil cuando su código contiene genéricos o expresiones lambda.

Problemas con anotaciones

Pueden surgir problemas cuando su bloque de código contiene una anotación. Probablemente sea porque cuando el @signo aparece al comienzo de la línea Javadoc, se considera una etiqueta Javadoc como @paramo @return. Por ejemplo, este código podría analizarse incorrectamente:

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

El código anterior desaparecerá por completo en mi caso.

Para solucionar esto, la línea no debe comenzar con un @signo:

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

Tenga en cuenta que hay dos espacios entre @codey @Override, para mantener las cosas alineadas con las siguientes líneas. En mi caso (usando Apache Netbeans) se representa correctamente.

Hay una diferencia significativa entre <blockquote><pre>...y <pre>{@code....El primero omitirá las declaraciones de tipo en genéricos, pero el segundo lo mantendrá.

E.g.: List<MyClass> myObject = null; muestra como List myObject = null;con los primeros y como List<MyClass> myObject = null;con el segundo

Si eres desarrollador de Android puedes usar:

<pre class=”prettyprint”>

TODO:your code.

</pre>

Para imprimir bastante su código en Javadoc con código Java.

Intente reemplazar "código" con "pre". La etiqueta previa en HTML marca el texto como preformateado y todos los avances de línea y espacios aparecerán exactamente a medida que los escribe.

Acabo de leer la referencia de Javadoc 1.5 aquí , y solo el código con <y >debe estar encerrado dentro {@code ...}. Aquí un ejemplo simple:

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

Adjunto mi código de ejemplo con <pre class="brush: java"></pre>etiquetas y uso SyntaxHighlighter para javadocs publicados. No perjudica al IDE y hace que los ejemplos de código publicados sean hermosos.

Usando Java SE 1.6, parece que todos los identificadores de MAYÚSCULAS PRE son la mejor manera de hacer esto en Javadoc:

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

Es la forma más sencilla de hacer esto.

Un ejemplo de un javadoc que obtuve de un método java.awt.Event:

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

Esto produce una salida que se ve exactamente como el código regular, con espacios de código regulares y nuevas líneas intactas.

Al menos en Visual Studio Code, puede forzar un comentario Javadoc para que respete los saltos de línea envolviéndolo en triples, como se ve a continuación:

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