Documentez votre code Java automatiquement avec Javadoc

Si vous faites n'importe quel type de programmation, vous savez bien que l'une des tâches les plus fastidieuses consiste à documenter votre code. Que vous trouviez cela légèrement ennuyeux ou une entreprise que vous affrontez avec une peur absolue, la documentation du code est essentielle. D'autres ont besoin de comprendre comment fonctionne votre code, et vous pourriez même être l'un d'entre eux si vous le lisez plus tard !

Java fournit commodément une solution intégrée au problème: Javadoc.

Javadoc peut vous aider à documenter votre code automatiquement

J'espère que vous suivez déjà bonnes pratiques de codage et incluez des commentaires explicatifs dans votre code. Bien que ce type de commentaire dans le code soit certainement utile, il ne fournit rien de comparable à un manuel.

Bien sûr, un autre programmeur peut parcourir votre code et lire les classes, méthodes et fonctions spécifiques qui se trouvent devant lui. Il est cependant extrêmement difficile d'avoir une bonne vue d'ensemble de tout le code ou de trouver des fonctions qui pourraient être utiles quand on ne sait pas qu'elles existent. Javadoc vise à résoudre ce problème.

Javadoc générera automatiquement un manuel HTML détaillé et convivial pour l'ensemble de votre code. Mieux encore, il le fait en utilisant des commentaires de code que vous écrivez probablement déjà.

Qu'est-ce que Javadoc exactement et comment ça marche ?

Javadoc est un programme autonome fourni avec les versions du kit de développement Java (JDK) d'Oracle. En fait, vous ne pouvez pas le télécharger séparément. Lorsque vous téléchargez et installer l'une des versions du JDK d'Oracle, il installera également Javadoc.

Lorsque vous l'exécutez, Javadoc génère une documentation HTML à partir de commentaires spécialement formatés dans votre code source Java. Ce processus crée une documentation plus utile et lisible tout en encourageant les meilleures pratiques.

En un mot, Javadoc vous permet d'écrire votre code et sa documentation en même temps. Il simplifie votre flux de travail et vous permet d'utiliser votre temps plus efficacement.

Javadoc fonctionne en analysant les commentaires spécialement formatés dans votre code et en les convertissant en sortie HTML. Le seul changement que vous devez vraiment apporter est d'inclure certaines chaînes dans vos commentaires. Ceux-ci permettent à Javadoc de savoir ce que vous souhaitez inclure dans la documentation finale.

Les commentaires Javadoc doivent précéder immédiatement une déclaration de classe, de champ, de constructeur ou de méthode. Le commentaire lui-même doit :

• Commencez par les trois personnages /**.
• Inclure un astérisque au début de chaque nouvelle ligne.
• Fermer avec les deux personnages */.

Dans les commentaires, vous pouvez inclure du HTML dans la sortie finale et inclure des balises qui généreront des liens vers des parties pertinentes de votre base de code. Vous pouvez même utiliser des éléments tels que des balises d'image HTML pour inclure des images dans la documentation finale. Une fois que vous vous êtes habitué au format et aux balises disponibles, écrire de tels commentaires est un jeu d'enfant.

Voici un exemple pour illustrer des commentaires Javadoc simples décrivant une fonction qui obtient une image à partir d'une URL et l'imprime à l'écran. Le commentaire précède immédiatement la fonction et décrit ce qu'elle fait. Ce bloc de commentaires utilise également trois balises spécifiques à la section: @param, @revenir, et @voir.

/**
* Renvoie un objet Image qui peut ensuite être peint à l'écran.
* L'argument url doit spécifier un absolu {@lien URL}. Le nom
* L'argument est un spécificateur relatif à l'argument url.
* 

* Cette méthode revient toujours immédiatement, que le
* l'image existe. Lorsque cette applet tente de dessiner l'image sur
* l'écran, les données seront chargées. Les primitives graphiques
* qui dessinent l'image seront progressivement peintes sur l'écran.
*
* @param url une URL absolue donnant l'emplacement de base de l'image
* @param nommer l'emplacement de l'image, par rapport à l'argument url
* @revenir l'image à l'URL spécifiée
* @voir Image
*/
Publique Image obtenirImage(URL URL, nom de chaîne){
essayer {
revenir obtenirImage(Nouveau URL(url, nom));
 } attraper (MalformedURLException e) {
revenirnul;
 }
}

Lorsque Javadoc traite le code ci-dessus, il génère une page Web semblable à la suivante :

Un navigateur rend la sortie Javadoc de la même manière qu'il affiche n'importe quel document HTML. Javadoc ignore les espaces blancs supplémentaires et les sauts de ligne, sauf si vous utilisez des balises HTML pour créer cet espace.

Les @tags utilisés à la fin du commentaire génèrent le Paramètres, Retour, et Voir également sections que vous voyez.

Vous devriez suivre le @param balise avec le nom du paramètre, un espace et une description de celui-ci. Dans le cas ci-dessus, il y a deux paramètres: URL et Nom. Notez que les deux apparaissent sous le même en-tête Paramètres dans la sortie de la documentation. Vous pouvez lister autant de paramètres que nécessaire pour la fonction ou la méthode que vous décrivez.

La @revenir La balise documente la valeur renvoyée par la fonction, le cas échéant. Il peut s'agir d'une simple description d'un mot ou de plusieurs phrases, selon les circonstances.

La @voir tag vous permet de marquer d'autres fonctions qui sont liées ou pertinentes. Dans ce cas, la balise @see fait référence à une autre fonction appelée simplement Image. Notez que les références faites avec cette balise sont des liens cliquables, permettant à un lecteur d'accéder directement à l'élément référencé dans le code HTML final.

D'autres balises sont disponibles, telles que @version, @author, @exception et autres. Lorsqu'elles sont utilisées correctement, les balises aident à relier les éléments les uns aux autres et permettent de naviguer facilement dans la documentation.

Exécuter Javadoc sur votre code source

Vous appelez Javadoc sur la ligne de commande. Vous pouvez l'exécuter sur des fichiers uniques, des répertoires entiers, des packages Java ou sur une liste de fichiers individuels. Par défaut, Javadoc générera les fichiers de documentation HTML dans le répertoire où vous entrez la commande. Pour obtenir de l'aide sur les commandes spécifiques disponibles, entrez simplement :

javadoc --aider

Pour voir exactement ce que Javadoc peut faire plus en détail, consultez la documentation officielle de Oracle. Pour créer un ensemble rapide de documentation sur un seul fichier ou répertoire, vous pouvez entrer javadoc sur la ligne de commande suivi d'un nom de fichier ou d'un caractère générique.

javadoc ~/code/nomfichier.java
javadoc ~/code/*.Java

Ci-dessus se trouve une liste des fichiers et répertoires créés par Javadoc. Comme vous pouvez le voir, il y en a pas mal. Pour cette raison, vous devez vous assurer que vous n'êtes pas dans le même répertoire que votre code source lorsque vous exécutez le programme. Cela pourrait créer tout un gâchis.

Pour afficher vos documents nouvellement créés, ouvrez simplement le index.html fichier dans votre navigateur préféré. Vous obtiendrez une page comme celle-ci :

Il s'agit de la documentation d'une seule et courte classe Java pour illustrer la sortie. L'en-tête indique le nom de la classe ainsi que les méthodes qu'elle contient. Faire défiler vers le bas révèle des définitions plus détaillées de chacune des méthodes de classe.

Comme vous pouvez le voir, pour tout type de projet Java, en particulier les grands avec plusieurs milliers de lignes de code, ce type de documentation est inestimable. Ce serait un défi d'en savoir plus sur une grande base de code en lisant son code source. Les pages Javadoc rendent ce processus beaucoup plus rapide et plus facile à suivre.

Javadoc peut vous aider à garder votre code Java et toute la documentation pertinente organisés et faciles à utiliser. Que vous le fassiez pour votre futur moi oublieux ou pour faciliter les choses pour une grande équipe, Javadoc est un outil puissant qui peut changer la façon dont vous écrivez et interagissez avec votre codage Java projets.

Les 8 meilleurs blogs Java pour les programmeurs

Lire la suite