Ant - Documentación de compilación

La documentación es imprescindible en cualquier proyecto. La documentación juega un papel importante en el mantenimiento de un proyecto. Java facilita la documentación mediante el uso dejavadocherramienta. Ant lo hace aún más fácil al generar la documentación bajo demanda.

Como sabe, la herramienta javadoc es muy flexible y permite varias opciones de configuración. Ant expone estas opciones de configuración a través de la tarea javadoc. Si no está familiarizado con los javadocs, le sugerimos que comience con este Tutorial de documentación de Java .

La siguiente sección enumera las opciones de javadoc más comúnmente utilizadas en Ant.

Atributos

La fuente se puede especificar usando sourcepath, sourcepathref o sourcefiles.

• sourcepath se utiliza para apuntar a la carpeta de los archivos de origen (por ejemplo, carpeta src).

• sourcepathref se utiliza para hacer referencia a una ruta a la que hace referencia el atributo de ruta (por ejemplo, delegates.src.dir).

• sourcefiles se utiliza cuando desea especificar los archivos individuales como una lista separada por comas.

La ruta de destino se especifica mediante el destdir carpeta (por ejemplo, build.dir).

Podrías filtrar el javadoctarea especificando los nombres de los paquetes que se incluirán. Esto se logra utilizando elpackagenames atributo, una lista separada por comas de archivos de paquetes.

Puede filtrar el proceso javadoc para mostrar solo las clases y miembros públicos, privados, de paquete o protegidos. Esto se logra utilizando elprivate, public, package y protected atributos.

También puede decirle a la tarea javadoc que incluya el autor y la información de la versión usando los atributos respectivos.

También puede agrupar los paquetes utilizando el group atributo, para que sea fácil de navegar.

Poniendolo todo junto

Continuemos nuestro tema del Hello worldSolicitud de fax. Agreguemos un objetivo de documentación a nuestro proyecto de aplicación de fax.

A continuación se muestra una tarea javadoc de ejemplo utilizada en nuestro proyecto. En este ejemplo, hemos especificado el javadoc para usar elsrc.dir como directorio de origen, y doc como el objetivo.

También hemos personalizado el título de la ventana, el encabezado y la información del pie de página que aparecen en las páginas de documentación de Java.

Además, hemos creado tres grupos:

• uno para las clases de utilidad en nuestra carpeta de origen,
• uno para las clases de interfaces de usuario, y
• uno para las clases relacionadas con la base de datos.

Puede notar que el grupo de paquetes de datos tiene dos paquetes: faxapp.entity y faxapp.dao.

<target name = "generate-javadoc">
   <javadoc packagenames = "faxapp.*" sourcepath = "${src.dir}" 
      destdir = "doc" version = "true" windowtitle = "Fax Application">
      
      <doctitle><![CDATA[= Fax Application =]]></doctitle>
      
      <bottom>
         <![CDATA[Copyright © 2011. All Rights Reserved.]]>
      </bottom>
      
      <group title = "util packages" packages = "faxapp.util.*"/>
      <group title = "web packages" packages = "faxapp.web.*"/>
      <group title = "data packages" packages = "faxapp.entity.*:faxapp.dao.*"/>
   </javadoc>

   <echo message = "java doc has been generated!" />
</target>

Ejecutemos la tarea Ant javadoc. Genera y coloca los archivos de documentación de Java en la carpeta doc.

Cuando el javadoc target se ejecuta, produce el siguiente resultado:

C:\>ant generate-javadoc
Buildfile: C:\build.xml

java doc has been generated!

BUILD SUCCESSFUL
Total time: 10.63 second

Los archivos de documentación de Java ahora están presentes en el doc carpeta.

Normalmente, los archivos javadoc se generan como parte de los destinos de lanzamiento o paquete.