Herramientas de usuario

Herramientas del sitio


bloque4:javadoc

¡Esta es una revisión vieja del documento!


JavaDoc - Documentación de Clases

Javadoc es una utilidad incluida en el Kit de Desarrollo de Java (JDK) para la generación de documentación de APIs en formato HTML a partir de código fuente Java. La aplicación javadoc está incluida en la carpeta bin del directorio del JDK de Java, junto a otros programas como java, javac, jar, etc.

Javadoc es el estándar para documentar clases de Java. La mayoría de los IDEs para Java utilizan javadoc para generar de forma automática documentación de clases.

Documentar las clases

Veamos en primer lugar qué se debe incluir al documentar una clase:

  • Nombre de la clase, descripción general, número de versión, nombre de autores.
  • Documentación de cada constructor o método (especialmente los públicos) incluyendo:
    • nombre del constructor o método, tipo de retorno, nombres y tipos de parámetros si los hay, descripción general, descripción de parámetros (si los hay), descripción del valor que devuelve.
  • Las variables de instancia o de clase no se suelen documentar a nivel de javadoc. Solo las constantes, si hubiera.

Aspectos a tener en cuenta

  • La documentación para javadoc ha de incluirse entre símbolos de comentario que han de empezar con una barra y doble asterisco, y terminar con un asterisco y barra simple.
/**
 *    Esto es un comentario para javadoc 
 */
  • La ubicación del comentario le define a javadoc qué representa el comentario:
    • si está incluido justo antes de la declaración de clase se considerará un comentario de clase,
    • si está incluido justo antes de la signatura de un constructor o método se considerará un comentario de ese constructor o método.
    • lo mismo en caso de una constante de clase.
  • Para alimentar javadoc se usan ciertas palabras reservadas (tags) precedidas por el carácter “@”, dentro de los símbolos de comentario javadoc. Si no existe al menos una línea que comience con @ no se reconocerá el comentario para la documentación de la clase.

Tags o Etiquetas

Documentación de clases e interfaces En el comentario de cada clase o interface se debe explicar para que sirve esa clase o interface.

Deben usarse al menos las etiquetas:

  • @author
  • @version

Documentación de constructores y métodos

En el comentario de cada método se debe explicar para que sirve ese método.

Deben usarse al menos las etiquetas:

  • @param: una por argumento de entrada, indicando el tipo, y su funcionalidad
  • @return: indicando el tipo y su funcionalidad, si el método no es void
  • @exception ó @throws: una por tipo de Exception que se puede lanzar, solo si se lanzan (@exception y @throws se pueden usar indistintamente).

Generar Javadoc en Eclipse

Selecionamos el proyecto del que necesitamos obtener el Javadoc y vamos a Project → Generate Javadoc

  • Si el campo de Javadoc command está vacío indicamos la ruta de nuestro javadoc.exe (En este caso puntual C:\Program Files\Java\jdk***\bin\javadoc.exe).
  • Luego indicamos la carpeta de destino y seguimos el asistente.

  • Por defecto usaremos la ubicación estándar, que siempre es en nuestra carpeta base del proyecto que contiene las clases que queremos documentar, en un nuevo directorio llamado doc.
  • Al pulsar finalizar, se habrá generado un directorio doc en la ruta específicada.
  • Si abrimos el fichero index.html accederemos a la documentación de nuestro proyecto.

JavaDoc es una aplicación que viene en el paquete JDK de Java, debemos tener ese paquete para poder usarlo y seleccionaremos el programa Javadoc.exe contenido en la carpeta bin (binarios) de la carpeta de nuestro jdk. Normalmente en “Archivos de programa /Java”


© 2025 Fernando Valdeón

bloque4/javadoc.1520012378.txt.gz · Última modificación: 16/09/2024 20:53 (editor externo)