una - programa java comentado
Ejemplo de código de múltiples líneas en comentario Javadoc (14)
Tengo un pequeño código de ejemplo 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 dar formato a los ejemplos de código en los comentarios de Javadoc?
Acabo de leer la referencia de Javadoc 1.5 here , y solo el código con < y > debe estar incluido dentro de {@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 ...
Además de las etiquetas <pre> ya mencionadas, también debe usar la anotación @code JavaDoc, que facilitará mucho la vida 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á la salida HTML correcta:
Set<String> s;
System.out.println(s);
Al omitir el bloque @code (o usar una etiqueta <code> ) se obtendrá un HTML como este:
Set s;
System.out.println(s);
(Para referencia, las descripciones de las etiquetas de Java SE 8 se pueden encontrar aquí: Etiquetas Javadoc )
Adjunte su código multilínea con etiquetas <pre></pre> .
Aquí están mis dos centavos.
Como ya se indica en las otras respuestas, debe usar <pre> </pre> junto con {@code } .
Usa pre y {@code}
- Envolver su código dentro de
<pre>y</pre>evita que su código se colapse en una línea; - El ajuste de su código dentro de
{@code}evita que<,>y todo lo que está en medio desaparezca. Esto es particularmente útil cuando su código contiene expresiones genéricas o lambda.
Problemas con las anotaciones.
Pueden surgir problemas cuando su bloque de código contiene una anotación. Probablemente sea así porque cuando el signo @ aparece al principio de la línea Javadoc, se considera una etiqueta Javadoc como @param o @return . Por ejemplo, este código podría ser analizado incorrectamente:
/**
* Example usage:
*
* <pre>{@code
* @Override
* public void someOverriddenMethod() {
El código anterior desaparecerá completamente 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 @code y @Override , para mantener las cosas alineadas con las siguientes líneas. En mi caso (usando Apache Netbeans) se renderiza correctamente.
Encierro mi código de ejemplo con etiquetas <pre class="brush: java"></pre> y uso SyntaxHighlighter para javadocs publicados. No hace daño al IDE y hace que los ejemplos de código publicados sean hermosos.
Hay una diferencia significativa entre <blockquote><pre>... y <pre>{@code.... El primero omitirá las declaraciones de tipo en los genéricos, pero el último lo mantendrá.
Eg: List<MyClass> myObject = null; se muestra como List myObject = null; con los primeros y como List<MyClass> myObject = null; con el segundo
Intente reemplazar "código" con "pre". La etiqueta pre en HTML marca el texto como preformateado y todos los saltos de línea y espacios aparecerán exactamente a medida que los escriba.
La fuente java tiene muchos buenos ejemplos para esto. Aquí hay un ejemplo de la cabeza 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>
...
Me fue muy difícil 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 la etiqueta
<code>antigua - para evitar que se interpreten los corchetes - uso de la etiqueta "nueva"
{@code ...}- para obtener los genéricos incluidos en la salida - escapando del signo @ en
@Overridetravés de "{@literal @}Override" porque el generador de javadoc "se inclina" allí debido al hecho de que @ va directamente después de un soporte 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();
Necesita las etiquetas <pre></pre> para los saltos de línea y {@code ... } dentro de ellos para los genéricos. Pero entonces no está permitido colocar la llave de apertura en la misma línea que la etiqueta <generic> , porque entonces todo se mostrará de nuevo en 1 línea.
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 al pegar la llave de cierre de {@code , se muestra:
* ..
* <pre>
* {@code
* public List<Object> getObjects()
* {
* return objects;
* }
* }
* </pre>
* ..
Salida:
public List<Object> getObjects()
{
return objects;
}
}
Pude generar archivos HTML atractivos con el siguiente snip-it 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 generada de javadoc en la figura 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 reformatear 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 primer <pre> ahora se divide en dos líneas. El código 2 genera el archivo HTML javadoc generado como se muestra en la Fig. 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 sigue teniendo el formato esperado, 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 que se muestra en la Fig. 1.
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.
Usando Java SE 1.6, parece que todos los identificadores de UPPERCASE PRE es 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 los espacios entre códigos regulares y las nuevas líneas intactas.
/**
* <blockquote><pre>
* {@code
* public Foo(final Class<?> klass) {
* super();
* this.klass = klass;
* }
* }
* </pre></blockquote>
**/
-
<pre/>se requiere para preservar líneas. -
{@codedebe tener su propia línea -
<blockquote/>es solo para sangría.
public Foo(final Class<?> klass) {
super();
this.klass = klass;
}
ACTUALIZACIÓN con JDK8
Los requisitos mínimos para los códigos apropiados 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 una <blockquote/> opcional que rodea 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 con <p> y </p> produce advertencias.