Ant - Documentação de Construção

A documentação é essencial em qualquer projeto. A documentação desempenha um grande papel na manutenção de um projeto. Java facilita a documentação pelo uso da ferramenta javadoc incorporada. O Ant facilita ainda mais, gerando a documentação sob demanda.

Como você sabe, a ferramenta javadoc é altamente flexível e permite várias opções de configuração. O Ant expõe essas opções de configuração através da tarefa javadoc. Se você não estiver familiarizado com o javadocs, sugerimos que você comece com este Tutorial de documentação do Java .

A seção a seguir lista as opções javadoc mais usadas no Ant.

Atributos

A origem pode ser especificada usando caminho de origem , caminho de origemref ou arquivos de origem .

  • sourcepath é usado para apontar para a pasta dos arquivos de origem (por exemplo, pasta src).

  • sourcepathref é usado para referenciar um caminho que é referenciado pelo atributo path (por exemplo, delegates.src.dir).

  • Os arquivos de origem são usados quando você deseja especificar os arquivos individuais como uma lista separada por vírgula.

O caminho de destino é especificado usando a pasta destdir (por exemplo, build.dir).

Você pode filtrar a tarefa javadoc especificando os nomes dos pacotes a serem incluídos. Isso é obtido usando o atributo packagenames , uma lista separada por vírgula de arquivos de pacote.

Você pode filtrar o processo javadoc para mostrar apenas as classes e membros públicos, privados, de pacotes ou protegidos. Isso é obtido usando os atributos private , public , package e protected .

Você também pode dizer à tarefa javadoc para incluir as informações do autor e da versão usando os respectivos atributos.

Você também pode agrupar os pacotes usando o atributo group , para facilitar a navegação.

Juntando tudo

Vamos continuar nosso tema do aplicativo de fax Hello world . Vamos adicionar um destino de documentação ao nosso projeto de aplicativo de fax.

Dado a seguir é um exemplo de tarefa javadoc usada em nosso projeto. Neste exemplo, especificamos o javadoc para usar o src.dir como o diretório de origem e o doc como o destino.

Também personalizamos o título da janela, o cabeçalho e as informações do rodapé que aparecem nas páginas de documentação do java.

Além disso, criamos três grupos -

  • um para as classes de utilitário em nossa pasta de origem,
  • um para as classes de interfaces de usuário e
  • um para as classes relacionadas ao banco de dados.

Você pode perceber que o grupo de pacotes de dados possui dois pacotes - faxapp.entity e 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>

Vamos executar a tarefa Ant javadoc. Ele gera e coloca os arquivos de documentação java na pasta doc.

Quando o destino javadoc é executado, ele produz o seguinte resultado -

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

java doc has been generated!

BUILD SUCCESSFUL
Total time: 10.63 second

Os arquivos de documentação do java agora estão presentes na pasta doc .

Normalmente, os arquivos javadoc são gerados como parte dos destinos de release ou pacote.