Generar documentacion de nuestro proyecto

De ChuWiki

Viene de Tutorial de Maven

En el pom.xml de nuestro proyecto maven podemos incluir algo de documentación sobre nuestro proyecto (desarrolladores, url del proyecto, etc). También, a base de añadir plugins, podemos generar documentación como javadoc, reporte de métricas, cobertura de los test, etc, etc. No vamos a ver aquí todos con detalle porque sería muy extenso. Simplemente una pequeña introducción sobre algunos de los informes que podemos sacar.

El comando mvn site generará la documentación html de nuestro proyecto e incluirá en ella unos informes por defecto. Más adelante veremos como configurar todo esto. De mano, podemos añadir algunos datos en nuestro pom.xml para que aparezcan en dicha documentación.

Url del proyecto[editar]

La URL del proyecto aparecerá cuando generemos la documentación html del mismo. Se edita el pom.xml y se busca al principio el tag <url>, que por defecto apuntará al sitio de maven. Podemos poner la url que queramos, normalmente la de la página web del proyecto, la de la empresa o la nuestra personal.

<project>
   ...
   <url>http://chuidiang.org</url>
   ...

Desarrolladores[editar]

Para indicar los desarrolladores que han participado en el proyecto, pondremos el tag <developers> y dentro de él tantos tag <developer> como queramos. Los datos que se pueden dar de cada desarrollador son como los siguientes

<project>
   ...
   <developers>
      <developer>
         <id>chui</id>
         <name>chuidiang</name>
         <email>chuidiang@aqui.com</email>
         <organization>chuidiang.com</organization>
         <organizationUrl>http://www.chuidiang.com</organizationUrl>
         <roles>
            <role>Brown eater</role>
            <role>Lo toca todo y no deja titere con cabeza</role>
            <role>Se bueno</role>
         </roles>
      </developer>
      ...
   </developers>

Esta información también aparecerá en la documentación html cuando la generemos.

Sistema de gestión de errores[editar]

Si nuestro proyecto tiene una URL donde se registren los errores que se encuentren en la aplicación, también podemos ponerlo

<project>
   ...
   <issueManagement>
      <system>Redmine</system>
      <url>http://url-proyecto.com/redmine:3000/</url>
   </issueManagement>

Informes del proyecto[editar]

Con maven podemos generar muchos tipos de informes para nuestro proyecto. Por ejemplo, podemos generar el javadoc, un reporte de métricas de código pmd, o un análisis de cobertura de código por parte de nuestros test de JUnit. Para generar estos informes, normalmente no es necesario hacer nada, salvo llamar al comando adecuado. Para los tres casos que hemos puesto, los comandos serían mvn site, mvn javadoc:javadoc, mvn pmd:pmd y mvn cobertura:cobertura. Estos comandos se bajarán los plugins necesarios y se ejecutarán con su configuración por defecto. Dejarán los resultados en el subdirectorio target/site del proyecto. Puedes ver todos los informes que se pueden generar en el apartado "reporting plugins" de http://maven.apache.org/plugins/index.html

En el sitio html básico de nuestro proyecto aparecerá la información que hemos puesto en los pasos anteriores como la URL del proyecto, los desarrolladores, el sistema de gestión de errores, etc. Es posible que nos interese que en el sitio html de nuestro proyecto se incluya más información además de la básica, como los informes que acabamos de comentar de javadoc, pmd o cobertura. Para ello, en el fichero pom.xml debemos añadir un tag <reporting> y dentro de él indicar qué informes queremos que se generen e incluyan automáticamente en nuestro sitio html. De esta forma, cuando ejecutemos mvn site, también se ejecutarán los javadoc, pmd o cobertura.

Puedes ver un ejemplo de la documentación generada por maven, con javadoc, fuentes y cobertura incluidos en http://proyectos.chuidiang.org/graficos/index.html

Generar el javadoc[editar]

Para generar el javadoc, basta con llamar al comando mvn javadoc:javadoc. Esto generará en el directorio target/site/apidocs del proyecto la documentación javadoc. Si queremos que esta documentación se genere automáticamente cuando vayamos a construir toda la documentación html de nuestro sitio web, debemos añadir

<project>
   ...
   <reporting>
      <plugins>
         <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <configuration>
               <source>1.5</source>
               <maxmemory>512</maxmemory>
            </configuration>
         </plugin>
         ...
      </plugins>
   </reporting>
   ...

Una vez hecho esto, el comando mvn site, generará la documentación html para el sitio web de nuestro proyecto y le incluirá el javadoc como parte del sitio.

Cobertura de los test de JUnit[editar]

Si nuestro proyecto maven tiene test de JUnit en src/main/test, podemos sacar un informe de cobertura de código. Este informe nos dice por cuántas líneas de código han pasado los test de JUnit y por cuales no ha pasado. Si queremos que este informe se añada automáticamente a la documentación html de nuestro proyecto, debemos añadir las siguientes líneas en el pom.xml

<project>
  ...
  <reporting>
     <plugins>
        <plugin>
           <groupId>org.codehaus.mojo</groupId>
           <artifactId>cobertura-maven-plugin</artifactId>
        </plugin>
        ...
     </plugins>
  </reporting>
  ...

Puedes ver detalles en informe de cobertura de los test Junit.

Informe de métricas de código[editar]

Otro posible informe son la métricas de nuestro código. Para que dicho informe se genere automáticamente al generar la documentación html de nuestro sitio, debemos añadir el siguiente trozo de código en nuestro pom.xml

<project>
  ...
  <reporting>
      <plugins>
         <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-pmd-plugin</artifactId>
         </plugin>
      </plugins>
   </reporting>

Por supuesto, se puede configurar qué reglas quieres que se tengan en cuenta, añadir más o quitar parte de las que hay. Incluso se puede configurar el plugin en el pom.xml para que el compilado falle si no cumple métricas. Tienes los detalles en la página oficial del proyecto https://pmd.github.io/

Puedes ver detalles en Maven y PMD