Spanish (Español) translation by Rodney Martinez (you can also view the original English article)
Esta lección rápida trata sobre Javadoc, una herramienta útil para generar documentación desde sus archivos fuentes de Java. Esta lección es parte de una serie en curso de tutoriales para desarrolladores que están aprendiendo Java para desarrollar aplicaciones para Android.
¿Qué es Javadoc?
Javadoc es una utilidad proporcionada con Java SDk que permite a los desarrolladores generar documentación del código desde los archivos fuentes de Java. Los ambientes de desarrollo como Eclipse tienen incorporado soporte para Javadoc y pueden generar materiales de consulta HTML indexado desde los comentarios de Javadoc. De hecho, la referencia Android SDK es un formulario de la documentación de Javadoc.
¿Cómo funciona Javadoc?
La documentación de Javadoc usa una combinación de procesamiento de código fuente (y la inspección de tipos, parámetros, etc.) y lectura en especial de las etiquetas de los comentarios que los desarrolladores ofrecen como metadatos asociados con una sección de código.
Un comentario estilo Javadoc debe venir antes de que el código esté asociado en él. Por ejemplo, un comentario Javadoc para una clase debería estar arriba de la declaración de la clase y un comentario par aun método debería estar arriba de la declaración del método. Cada comentarios debería comenzar con una corta descripción, seguido por una opción de descripción larga. Luego, puede incluir un número deferente de etiquetas de metadatos, que deben ser aplicados en un orden específico. Algunas etiquetas importantes incluyen:
- @autho - qué escribió este código
- @versión - cuando fue cambiada ésta
- @param - describe los parámetros de los métodos
- @return - describe los valores de retorno del método
- @throws - describe las excepciones thrown
- @see - enlaza a otro, ítem relacionado (ejemplo, "Ver también…").
- @since - describe cuando fue presentado el código (ejemplo, Nivel API).
- @deprecated - describe el ítem obsoleto y que alternativa usar en lugar de ése.
Usted puede crear sus etiquetas personalizadas para usarlas en la documentación.
Generar comentarios estilos Javadoc en Eclipse.
Si bien usted está escribiendo código en Eclipse, usted puede genera un comentario estilo Javadoc para seleccionar un ítem que usted quiere comentar (un nombre de clase, un nombre de un método, etcétera) y presionar las teclas ALT-SHIFT-J (Cmd-Shift-J en una Mac). Esto creará un comentario básico estilo Javadoc para que usted complete los detalles.
Simple Comentarios de Clases de Javadoc
Vamos a ver un ejemplo. Aquí está un simple comentario Javadoc que describe una clase:
/**
* Activity for loading layout resources
*
* This activity is used to display different layout resources for a tutorial on user interface design.
*
* @author LED
* @version 2010.1105
* @since 1.0
*/
public class LayoutActivity extends Activity {
Aquí está el aspecto que éste tendría cuando genere la documentación Javadoc.
Simples Comentarios de Casillas de Javadoc
Veamos un ejemplo. Aquí está un simple comentario Javadoc que describe una casilla dentro de una clase:
/** * Debug Tag for use logging debug output to LogCat */ private static final String DEBUG_TAG = "MyActivityDebugTag";
Aquí está el aspecto que éste tendría cuando genere la documentación Javadoc.
Simple Comentarios de Méotodos de Javadoc
Ahora veamos dos ejemplos de comentarios de métodos. Aquí está un simple comentario Javadoc que describe un método dentro de una clase:
/**
* Method that adds two integers together
*
* @param a The first integer to add
* @param b The second integer to add
* @return The resulting sum of a and b
*/
public int addIntegers(int a, int b)
{
return (a+b);
}
Ahora veamos un método que retorna voids pero lanza una excepción.
/**
* This method simply throws an Exception if the incoming parameter a is not a positive number, just for fun.
*
* @param a Whether or not to throw an exception
* @throws Exception
*/
public void throwException(boolean shouldThrow) throws Exception
{
if(shouldThrow == true)
{
throw new Exception();
}
}
Aquí está el aspecto que tendría cuando genere la documentación Javadoc para éstos dos métodos .
Generando la Documentación de Javadoc en Eclipse
Para generar la documentación Javadoc del código en Eclipse, vaya al menú Proyecto y escoja la opción "Generate Javadoc…". Esto lanzará un asistente que le permitirá escoger los proyectos para generar la documentación.
Desde este asistente, usted debería apuntar a Eclipse en la apropiado línea de herramienta javadoc.exe (la encontrará en su directorio JDS´s/bin). Además, puede configurar algunos ajustes de la documentación, tales como si para todo el código del documento o solamente para las clases visibles o los miembros, etc. Finalmente, escoja un destino para sus archivos de documentación.
Incluso sin generar archivos Javadoc, Eclipse le mostrará la documentación estilo Javadoc cuando usted desplace el cursos sobre sus métodos, tal como, cuando se muestra en la figura debajo.
Aprendiendo más sobre Javadoc
Usted puede encontrar más sobre la referencia Javadoc en el sitio web de Oracle. También, hay una útil sección Javadoc FAQ disponible.
Conclusión
En está rápida lección ha aprendido acerca de Javadoc, una herramienta poderosa usada por los desarrolladores de Java para documentar el código fuente a fondo para propósitos de referencia y mantenimiento. Eclipse, el ambiente de desarrollo utilizado por muchos desarrolladores de Android, tiene incorporado el soporte para Javadoc.
Acerca de los Autores
Desarrolladores de Celulares; Lauren Darcey y Shane Conder son coautores de varios libros sobre el desarrollo en Android: un libro de programación a fondo titulado: Desarrollo de Aplicaciones Inalámbricas de Android y Sams Aprenda usted mismo a Desarrollar Aplicaciones para Android en 24 horas. Cuando no escriben, ellos pasan su tiempo desarrollando programas para celulares en sus empresas y proporcionando servicios de consultoría. Ellos pueden ser localizado a través de correo electrónico:androidwirelessdev+mt@gmail.com o por medio de su blog en androidbook.blogspot.com y en Twitter @androidwireless.
¿Necesita más ayuda escribiendo aplicaciones de Android? ¡Revise nuestros últimos libros y recursos!
