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

531

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?

marca
fuente

Respuestas:

743

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 )

Fabian Steeg
fuente
63
Yo también lo habría pensado, pero desafortunadamente no es así, aún necesita agregar la etiqueta <pre> para obtener saltos de línea.
Fabian Steeg
12
Desafortunadamente, parece que cuando presionas ctrl + shift + F (formatear código en Eclipse), Eclipse desordena la etiqueta {@code} y la reemplaza con {& # 064; código ...
jpdaigle
3
@jpdaigle Acabo de probar esto en Eclipse Galileo y Helios y el formateador no reemplaza nada por mí (en Mac OS, pero tampoco he visto que el formateador haga algo así en otras plataformas).
Fabian Steeg
30
Otro desafortunado, si tiene bloques en su código de ejemplo usando llaves "{}", la primera llave de cierre terminará el bloque @code. Una forma de evitarlo es usar (espere ...) entidades html para las llaves. No veo un argumento convincente para las etiquetas <pre> para el código con bloques.
Ed Griebel
2
Eclipse desordena la etiqueta {@code} y la reemplaza con {& # 064; code- Esto no se debe a Eclipse, se debe a la utilidad javadoc (¿con errores?). Si tiene el carácter @ en el código multilínea dentro de {@code ... multiline ...} entonces javadoc no puede analizarlo correctamente :( Al menos esto es lo que veo con la implementación javadoc de Oracle JDK1.7.0_45.
Hombre
167

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();
Christoph Naber
fuente
2
Esto funciona pero recibo una advertencia cuando ejecuto javadoc generando esta advertencia "advertencia: {@code} dentro de <code>"
Shane Rowatt
3
Este es el que funcionó, la respuesta aceptada no funciona bien en mi eclipse (4.6.2).
Eric Wang
Me pregunto por qué todo esto es necesario, mi intellij 13 y posteriores funcionan bien con el código en la respuesta aceptada. ¿Es esto solo un problema de eclipse?
bvdb
Sí, también he visto que esto funciona bien en IntelliJ 11 y posteriores. IntelliJ lo maneja correctamente. Desafortunadamente, Eclipse NO representa el JavaDoc correctamente (estado de desplazamiento) e ignora tanto las nuevas líneas como los saltos html. Estoy tratando de encontrar una solución que funcione bien en ambos IDE, ya que son dos de los mejores IDE en uso hoy en día.
Michael M
41

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>
...
Steve B.
fuente
99
En resumen,<pre><blockquote>...</blockquote></pre>
Jin Kwon
66
Más bien<p><blockquote><pre> </pre></blockquote></p>
masterxilo
@JinKwon, lamentablemente, esto no siempre funciona, no en mi fragmento de código :( agregar un {@code al principio funciona, incluso si no se alcanzará el cierre}
benez
Esto parece funcionar para la mayoría de los códigos, pero no escapa a los corchetes angulares como en List<String>. Para eso estoy usando <pre>{@code ... }</pre>.
Daniel
24

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

Zach Scrivena
fuente
14

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;
}
}
Regla
fuente
44
Bienvenido a Stack Overflow. Para formatear el código en las publicaciones, puede prefijarlo (en un párrafo separado) por cuatro espacios o rodearlos con comillas (`` ...``). No necesitas <code>y <pre>etiquetas. Edité tu respuesta en esta mente.
Paŭlo Ebermann
10
/**
 * <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;
}


ACTUALIZAR con JDK8

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.

Jin Kwon
fuente
5

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.

bitsdanceforme
fuente
4

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.

MC Emperor
fuente
3

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

Tamas
fuente
2

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.

ifeegoo
fuente
1
Por favor explique: ¿qué debería hacer que esto funcione en las herramientas de Android, teniendo en cuenta los problemas que requieren la etiqueta @code? ¿Y qué componente debería definir la clase prettyprint? Android usa Javadoc regular.
noamtm
Xamarin / VS, Android Studio, ¿o no importa?
tyblu
@tyblu Android Studio funciona, pero es posible que Xamarin Studio / VS no funcione. Puede intentarlo.
ifeegoo
1

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.

Edwin
fuente
1

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 ...
mljrg
fuente
0

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.

Jarek Przygódzki
fuente
destacado preguntado en: stackoverflow.com/questions/1391614/…
Ciro Santilli 郝海东 冠状 病 六四 事件 法轮功
Con Syntax Highlighter debe cargar el script y corregir css. Parece increíble, pero debe poner la ruta correcta a los scripts y CSS requeridos. Además, si desea usar sin conexión, debe tener cuidado con las rutas correctas.
Alex Byrth
0

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.

Eugene_CD-adapco
fuente
2
Esto no agrega nada a las respuestas existentes.
madth3
madth3, tienes razón. Pensé que había visto una diferencia al usar premodificadores más bajos vs. MAYÚSCULAS, pero en una segunda mirada, no parece ser así. También podría tener algo que ver con cómo apareció en esta página web versus cómo aparece en javadoc.
Eugene_CD-adapco
1
mayúsculas y minúsculas en la etiqueta html?
Jasonw
0

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