-
Notifications
You must be signed in to change notification settings - Fork 1
guia implementacion comentarios
volver a Implementación
La documentación del código es fundamental, no sólo para que cualquiera que lea nuestro código pueda entenderlo, sino para que nosotros mismos consigamos recordarlo después de un tiempo sin tocarlo. Como regla general, la documentación se hará siguiendo las indicaciones de javadoc. Hay un buen manual de estilo en inglés en este enlace. Aquí se resume y se adapta este manual.
Javadoc es realmente una herramienta que genera unas páginas html con el mismo formato que la API de java a partir de nuestro código. Lo que hace Javadoc es interpretar unas etiquetas especiales puestas en la documentación de nuestras clases, métodos y funciones para generar la documentación del código. Para indicar que un comentario debe ser interpretado por Javadoc se utiliza esta cadena: /** en lugar de la típica de inicio de comentario '/*'. Por ejemplo:
#java /** *Este comentario lo interpreta <strong>javadoc</strong>. *@author Iván Castilla */ /* *Este comentario NO */
Las etiquetas de Javadoc se indican mediante una arroba @. En el ejemplo tenemos una etiqueta que indica que el autor de ese comentario es 'Iván Castilla'.
Un comentario de Javadoc admite código html, que se indica de la manera habitual.
Los comentarios de Javadoc deben anteceder a una clase, atributo o método. Un comentario Javadoc a mitad de un método será ignorado. Según la parte del código que esté antecediendo las etiquetas que pueden usarse son diferentes.
volver a Implementación