Cómo citar "* /" en JavaDocs

Tengo una necesidad de incluir */ en mi comentario de JavaDoc. El problema es que esta es también la misma secuencia para cerrar un comentario. ¿Cuál es la forma correcta de citar/escapar de esto?Cómo citar "* /" en JavaDocs

Ejemplo:

/** 
* Returns true if the specified string contains "*/". 
*/ 
public boolean containsSpecialSequence(String str)

Seguimiento: Parece que puedo utilizar / para la barra. El único inconveniente es que esto no es tan legible cuando se ve el código directamente en un editor de texto.

/** 
* Returns true if the specified string contains "*&#47;". 
*/

Fuente

2009-03-10 Steve Kuo

Me gustaría agregar que este es uno de los ejemplos perfectos de una buena pregunta. :) – Randolpho

Me gusta la sugerencia de Bobince de incluir "asterisco seguido de una barra inclinada", tal vez entre paréntesis después del literal "* /". Entonces es legible tanto en código como en Javadoc. – ide

Use HTML escaping.

Así que en su ejemplo:

/** 
* Returns true if the specified string contains "*&#47;". 
*/ 
public boolean containsSpecialSequence(String str)

/ se escapa como un carácter "/".

Javadoc debe insertar la secuencia escapada intacta en el HTML que genera, y que debe aparecer como "* /" en su navegador.

Si quieres ser muy cuidadoso, se puede escapar de ambos personajes: */ se traduce en */

Editar:

Seguimiento: Parece que puedo utilizar & # 47; para la barra oblicua. El único inconveniente es que esto no es del todo legible cuando ve el código directamente.

So? El punto no es que su código sea legible, el punto es que su código documentación sea legible. La mayoría de los comentarios de Javadoc incrustan HTML complejo para la explicación. Demonios, el equivalente de C# ofrece una completa biblioteca de etiquetas XML. He visto algunas estructuras bastante intrincadas allí, déjame decirte.

Edición 2: Si te molesta demasiado, es posible incrustar un comentario en línea no javadoc que explica la codificación:

/** 
* Returns true if the specified string contains "*&#47;". 
*/ 
// returns true if the specified string contains "*/" 
public boolean containsSpecialSequence(String str)

Fuente

2009-03-10 19:15:04 Randolpho

Me hubiera ido por el B. –

@Tom Hawtin: Eh, papa olla-ah-to. Cualquiera de los dos trabaja :) – Randolpho

¿Esto molesta a alguien más a excepción de mí? Ahora se ve bien en el JavaDoc pero es ilegible cuando solo estás mirando el código fuente ... –

Usar la entidad

*&#47;

En su Documentación se mostrará como un "* /"

Fuente

2009-03-10 19:15:27 cpatrick

Otra forma en la que me topé, solo por completitud: agregar s Un marcado HTML que no altera la salida entre el * y /.

/** 
    * *<b/>/ 
    */

En comparación con la solución de escape HTML, esto parece algo así como un truco feo, sino que también produce el resultado correcto en la salida HTML.

Fuente

2009-03-10 19:39:35 Jonik

No del todo; su sugerencia tal como está actualmente probablemente viole los doctypes html. Si alguien fuera a seguir este camino, sugeriría algo así como: * / para asegurarse de que las etiquetas están cerradas. – Randolpho

Ah, me preguntaba sobre eso, pero lo dejé así porque es la opción más corta y funcionó bien en IDEA (Ctrl-Q). Si no , * no /o * /suficiente? – Jonik

5

Yo sugeriría también se agrega una línea de comentario en algún lugar cerca diciendo algo como

// */ is html for */

Fuente

2009-03-10 19:44:32 hasen

7

/** * Returns true if the specified string contains "*/". */

Ésta es la solución 'correcta', sino por causa de legibilidad que probablemente iría a por:

/** * Returns true if the string contains an asterisk followed by slash. */

Fuente

2009-03-10 21:03:15 bobince

7

Nadie mencionó {@literal}. Esta es otra manera de ir:

/** * Returns true if the specified string contains "*{@literal /}". */

Lamentablemente no se puede escapar */ a la vez. Con algunos inconvenientes, esto también corrige:

El único inconveniente es que esto no es lo único que puede leer cuando se visualiza el código directamente en un editor de texto.

Fuente

2014-07-11 10:52:51

Respuesta

Cuestiones relacionadas