La constitution de la documentation dans un projet Java peut être simplement réalisé directement dans le code source en utilisant un formatage spécifique dans un commentaire.
Le système Javadoc existe depuis la création de Java (https://en.wikipedia.org/wiki/Javadoc) et invite le développeur à produire directement dans son programme la documentation.
En premier lieu, on peut documenter le package si un fichier package-info.java est disponible. Je vous renvoie vers cette documentation qui explique l’utilité de ce fichier: https://www.baeldung.com/java-package-info. Dans le cas d’un petit projet informatique, voici un commentaire explique l’utilisation d’un package:
/**
* main est le package principal du projet de test d'intégration de Jenkins
*/
package main;Pour faire la suite, nous allons documenter une classe Main dans le fichier main.java :
/**
* Classe de test pour l'intégration de Jenkins
* @author Pierre Jean
* @version 1.0
*/
public class Main {
Il faut être humble dans la constitution de la documentation. À mon avis, il vaut mieux produire la documentation progressivement en mettant les premiers éléments puis progressivement compléter cette documentation par ajout de détails.
L’étape suivante est l’ajout de la documentation d’une méthode basique.
/**
* Méthode pour afficher le double de ce nombre
* <p>
* Cette méthode sert pour tester l'intégration l'affichage d'un nombre.
* Ce nombre est calculé en appelant une méthode d'une classe Calcul
* qui retourne le double du nombre.
* <p>
* Cette méthode permet de réaliser un test unitaire avec Jenkins.
*
* @param nombre paramètre du nombre pour réaliser le doublement
* @return retourne le nombre affiché
*/
public int afficheDeuxFois(int nombre) {
System.out.println(Calcul.doublement(nombre));
return Calcul.doublement(nombre);
}J’ai ajouté beaucoup d’explication sur une méthode très basique pour détailler la forme de cette documentation avec un seul paramètre et une valeur de retour.
Nous pouvons maintenant imaginer la génération de la documentation sous la forme de pages HTML via le Menu Project > Generate Javadoc …
Puis dans l’interface suivante, on indique sur quel projet (ou quels projets) on souhaite générer la Javadoc et le dossier de génération de cette documentation.
La génération de la documentation va fabriquer différents fichiers HTML dans le dossier doc visible dans Eclipse. On doit donc indiquer si on souhaite réécrire dans le dossier en remplaçant l’ancien contenu.
La fabrication du contenu est visible dans Eclipse dans le dossier doc indiqué dans les étapes précédentes. Il suffit ensuite d’ouvrir le fichier index.html via le menu « Open With » > « Web Browser » pour afficher la documentation finale.
Le rendu final de la documentation est alors affiché dans une forme standardisé réalisant les liens entre les différentes pages de la documentation.
La création de la documentation est simplifiée et standardisée facilement. Chaque langage de programmation dispose de sa propre version de Javadoc.
