Ant - documentação de construção

A documentação é uma obrigação em qualquer projeto. A documentação desempenha um grande papel na manutenção de um projeto. Java torna a documentação mais fácil com o uso dejavadocferramenta. O Ant torna isso ainda mais fácil, 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 por meio da tarefa javadoc. Se você não estiver familiarizado com javadocs, sugerimos que comece com este Tutorial de documentação Java .

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

Atributos

A fonte pode ser especificada usando sourcepath, sourcepathref ou sourcefiles.

sourcepath é usado para apontar para a pasta dos arquivos de origem (por exemplo, pasta src).
sourcepathref é usado para referir-se a um caminho referenciado pelo atributo path (por exemplo, delegates.src.dir).
sourcefiles é usado quando você deseja especificar os arquivos individuais como uma lista separada por vírgulas.

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

Você pode filtrar o javadoctarefa especificando os nomes dos pacotes a serem incluídos. Isso é conseguido usando opackagenames atributo, uma lista separada por vírgulas de arquivos de pacote.

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

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 group atributo, para que seja fácil de navegar.

Juntando tudo

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

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

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

Além disso, criamos três grupos -

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

Você pode notar 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 do javadoc. Ele gera e coloca os arquivos de documentação java na pasta doc.

Quando o javadoc target é 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 java estão agora presentes no doc pasta.

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