En general se
refiere a todo aquel material que complementa al código ayudando a su
comprensión por las personas. Es básico para poder responsabilizarse de un
programa pues permite entenderlo para reparar defectos o mejorarlo.
En particular se
refiere a una forma especial de comentarios java, entremezclados con el código,
y que se caracterizan por
· comenzar con la cadena “/**”
· terminar con la cadena “*/”
Estos comentarios no pueden anidarse, ni entre sí, ni con comentarios de
tipo /* ... */. El compilador se limita a detectar la terminación, sin
preocuparse de si hay varios comentarios empezados.
·
incluir
algunas claves “@etiqueta” que se comentan más abajo.
|
comentarios de documentación |
|
/** * Parte descriptiva. * Que puede consistir de varias frases o párrafos. * Se puede escribir con formato HTML. * * @etiqueta texto específico de la etiqueta */ |
La forma
estructurada de estos comentarios permiten un tratamiento especial
·
los
entornos de desarrollo resaltan en colores su empleo
·
herramientas
como javadoc permiten generar páginas HTML (para navegadores)
Estos comentarios
se aplican a clases, campos y métodos.
|
etiquetas habituales |
|
clases |
|
@author nombre y/o filiación del autor |
|
@version código y/o fecha |
|
@see clase | campo | método |
|
campos |
|
@see clase | campo | método |
|
métodos |
|
@param identificador explicación del argumento |
|
@return explicación del resultado |
|
@exception identificador explicación de cuándo se lanza @throws identificador explicación de cuándo se lanza El identificador identifica la clase de excepción que se puede lanzar. |
|
@deprecated Indica que, aunque el método
existe, se recomienda no utilizarlo, típicamente porque hay otro método
alternativo. |
|
@see clase | campo | método |
|
ejemplo de documentación de clase |
|
/** * Ejemplo: círculos. * * @author José A. Mañas * @version 24.9.2008 */ public
class Circulo { |
|
ejemplo de documentación de método |
|
/** * Intersección de dos rectas. * * @param recta1 una recta. * @param recta2 otra recta. * @return punto en el que las rectas se cruzan. * @exception Paralelas si las rectas son paralelas o coincidentes. * @see Punto */ public Punto interseccion(Recta recta1, Recta recta2) throws Paralelas { ... }
|
Temas relacionados