Ejemplo de código de varias líneas en comentario Javadoc
Tengo un pequeño ejemplo de código que quiero incluir en el comentario de 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 de Javadoc?
Además de las <pre>etiquetas ya mencionadas, también deberías usar la @codeanotación JavaDoc, que te hará la vida mucho más fácil cuando se trata de problemas con entidades HTML (en particular con genéricos), por ejemplo:
* <pre>
* {@code
* Set<String> s;
* System.out.println(s);
* }
* </pre>
Dará una salida HTML correcta:
Set<String> s;
System.out.println(s);
Si bien omitir el @codebloque (o usar una <code>etiqueta) se obtendrá un HTML como este:
Set s;
System.out.println(s);
Como referencia, puede encontrar una lista completa de descripciones de etiquetas disponibles en Java SE 8 aquí .
Me costó mucho 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>la etiqueta antigua para evitar que se interpreten las llaves - uso de "nuevo"
{@code ...}: etiqueta para incluir los genéricos en la salida - escape del inicio de sesión @ a
@Overridetravés de "{@literal @}Override" porque el generador javadoc se "inclina" allí debido al hecho de que @ va directamente después de una llave de apertura - elimine 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 para esto. Aquí hay un ejemplo del encabezado 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á nuevamente en 1 línea.
Se muestra en una línea:
* ..
* <pre>
* {@code
* public List<Object> getObjects() {
* return objects;
* }
* </pre>
* ..
Muestra 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 de {@code, se muestra:
* ..
* <pre>
* {@code
* public List<Object> getObjects()
* {
* return objects;
* }
* }
* </pre>
* ..
Producción:
public List<Object> getObjects()
{
return objects;
}
}
