Documenter un package avec des diagrammes UML

C’est bien beau Javadoc mais ça manque quand même cruellement de visuels. Je vais rapidement expliquer comment remédier à ça.

Avant de me lancer dans un développement, j’aime bien noter rapidement mes idées et notamment faire un petit diagramme de classes en UML. En Java, j’utilise PlantUML dans mon IDE IntelliJ. PlantUML a 2 principaux avantages : il fait le taf et il est gratuit.

Pour installer PlantUML, il suffit d’ajouter le plugin à IntelliJ.

PlantUML pluginPour créer un diagramme de classe, on peut créer un fichier PlantUML (click droit sur un package > New > PlantUML File).

Dans cet exemple, j’ai une classe abstraite et deux classes dérivées :

Fichier puml

Cette visualisation peut être exportée en format image. Comme elle est destinée à être utilisée dans la Javadoc, je l’exporte dans le répertoire javadoc/doc-files.

On peut maintenant simplement référencer cette image dans la javadoc comme ceci :

/** Moteur du quiz
 *  <p>
 *     <img alt="UML class diagram" src="../doc-files/Quiz.png" >
 */
public abstract class Quiz {
    // ...
}

Si vous voulez documenter un package, il suffira de créer un fichier nommé package-info.java directement dans le package. Il contiendra une ligne avec le nom du package précédée de la javadoc.

/**
 * Jeu créé en TP de la vidéo <a href="https://www.youtube.com/watch?v=hSB3qPUJ7qE">Java intermédiaire 42 - TP Quiz</a>
 * <p>
 *     <ul>
 *         <li>main() se trouve dans Quizmain</li>
 *         <li>L'engine de jeu peut être soit graphique soit en mode console
 *         <br><img alt="UML class diagram" src="../doc-files/Quiz.png" ></li>
 *         <li>Les sets de question portent sur les capitales ou des exercices de math
 *         <br><img alt="UML class diagram" src="../doc-files/QuestionsGenerator.png" ></li>
 *     </ul>
 */
package Quiz;

Ce qui donnera ce résultat :

Résultat dans la JavaDoc

Tadaaaa 😉