Ant - Build Documentation

La documentazione è un must in qualsiasi progetto. La documentazione gioca un ruolo importante nella manutenzione di un progetto. Java semplifica la documentazione grazie all'uso del filejavadocattrezzo. Ant lo rende ancora più semplice generando la documentazione su richiesta.

Come sapete, lo strumento javadoc è altamente flessibile e consente una serie di opzioni di configurazione. Ant espone queste opzioni di configurazione tramite l'attività javadoc. Se non hai familiarità con javadocs, ti suggeriamo di iniziare con questo tutorial sulla documentazione di Java .

La sezione seguente elenca le opzioni javadoc più comunemente utilizzate che vengono utilizzate in Ant.

Attributi

La sorgente può essere specificata usando sourcepath, sourcepathref o sourcefiles.

• sourcepath è usato per puntare alla cartella dei file di origine (es. cartella src).

• sourcepathref viene utilizzato per fare riferimento a un percorso a cui fa riferimento l'attributo path (ad esempio, delegates.src.dir).

• sourcefiles viene utilizzato quando si desidera specificare i singoli file come elenco separato da virgole.

Il percorso di destinazione viene specificato utilizzando il destdir cartella (ad esempio build.dir).

Puoi filtrare il file javadocattività specificando i nomi dei pacchetti da includere. Ciò si ottiene utilizzando ilpackagenames attributo, un elenco separato da virgole di file di pacchetto.

È possibile filtrare il processo javadoc per mostrare solo le classi ei membri pubblici, privati, del pacchetto o protetti. Ciò si ottiene utilizzando ilprivate, public, package e protected attributi.

Si potrebbe anche dire all'attività javadoc di includere le informazioni sull'autore e sulla versione utilizzando i rispettivi attributi.

Puoi anche raggruppare i pacchetti usando il file group attributo, in modo che diventi facile da navigare.

Mettere tutto insieme

Continuiamo il nostro tema del Hello worldApplicazione fax. Aggiungiamo un obiettivo di documentazione al nostro progetto di applicazione Fax.

Di seguito è riportato un esempio di attività javadoc utilizzata nel nostro progetto. In questo esempio, abbiamo specificato il javadoc per utilizzare ilsrc.dir come directory di origine e doc come bersaglio.

Abbiamo anche personalizzato il titolo della finestra, l'intestazione e le informazioni sul piè di pagina che appaiono nelle pagine della documentazione di Java.

Inoltre, abbiamo creato tre gruppi:

• uno per le classi di utilità nella nostra cartella dei sorgenti,
• uno per le classi delle interfacce utente e
• uno per le classi relative al database.

È possibile notare che il gruppo di pacchetti di dati ha due pacchetti: 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>

Eseguiamo il task javadoc Ant. Genera e inserisce i file di documentazione java nella cartella doc.

Quando il javadoc target viene eseguito, produce il seguente risultato:

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

java doc has been generated!

BUILD SUCCESSFUL
Total time: 10.63 second

I file di documentazione java sono ora presenti in doc cartella.

In genere, i file javadoc vengono generati come parte del rilascio o delle destinazioni del pacchetto.