Ant - Documentation de construction

La documentation est un must dans tout projet. La documentation joue un grand rôle dans la maintenance d'un projet. Java facilite la documentation grâce à l'utilisation dujavadocoutil. Ant rend les choses encore plus faciles en générant la documentation à la demande.

Comme vous le savez, l'outil javadoc est très flexible et permet un certain nombre d'options de configuration. Ant expose ces options de configuration via la tâche javadoc. Si vous n'êtes pas familier avec les javadocs, nous vous suggérons de commencer par ce didacticiel de documentation Java .

La section suivante répertorie les options javadoc les plus couramment utilisées dans Ant.

Les attributs

La source peut être spécifiée en utilisant sourcepath, sourcepathref ou sourcefiles.

sourcepath est utilisé pour pointer vers le dossier des fichiers source (par exemple le dossier src).
sourcepathref est utilisé pour faire référence à un chemin référencé par l'attribut path (par exemple, Deleg.src.dir).
sourcefiles est utilisé lorsque vous souhaitez spécifier les fichiers individuels sous forme de liste séparée par des virgules.

Le chemin de destination est spécifié à l'aide du destdir dossier (par exemple build.dir).

Vous pouvez filtrer le javadoctâche en spécifiant les noms de packages à inclure. Ceci est réalisé en utilisant lepackagenames attribut, une liste de fichiers de package séparés par des virgules.

Vous pouvez filtrer le processus javadoc pour afficher uniquement les classes et membres publics, privés, de package ou protégés. Ceci est réalisé en utilisant leprivate, public, package et protected les attributs.

Vous pouvez également indiquer à la tâche javadoc d'inclure les informations sur l'auteur et la version à l'aide des attributs respectifs.

Vous pouvez également regrouper les packages en utilisant le group attribut, de sorte qu'il devient facile de naviguer.

Mettre tous ensemble

Continuons notre thème de la Hello worldApplication de télécopie. Ajoutons une cible de documentation à notre projet d'application Fax.

Vous trouverez ci-dessous un exemple de tâche javadoc utilisée dans notre projet. Dans cet exemple, nous avons spécifié le javadoc pour utiliser lesrc.dir comme répertoire source, et doc comme cible.

Nous avons également personnalisé le titre de la fenêtre, l'en-tête et les informations de pied de page qui apparaissent sur les pages de documentation java.

De plus, nous avons créé trois groupes -

un pour les classes utilitaires dans notre dossier source,
un pour les classes d'interfaces utilisateur, et
un pour les classes liées à la base de données.

Vous remarquerez peut-être que le groupe de packages de données comporte deux packages -– faxapp.entity et 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>

Exécutons la tâche Ant javadoc. Il génère et place les fichiers de documentation java dans le dossier doc.

Quand le javadoc target est exécuté, il produit le résultat suivant -

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

java doc has been generated!

BUILD SUCCESSFUL
Total time: 10.63 second

Les fichiers de documentation java sont maintenant présents dans le doc dossier.

En règle générale, les fichiers javadoc sont générés dans le cadre de la version ou du package cibles.