Discussion :

[Carlito_superheros]

Bonjour à tous,

Tout d'abord excusez-moi si je ne poste pas au bon endroit, je n'ai pas trouvé de forum réellement plus judicieux.
Voici le problème auquel je suis confronté, je travaille sur une librairie Java portant sur la Programmation par contraintes. Nous proposons un ensemble d'outils pour résoudre des problèmes avec la ppc.
Nous disposons d'une javadoc (peu ou mal utilisée), d'un ensemble de tests unitaires (orientés developpeur, assez complet) et d'exemples d'utilisation (orientés utilisateur).
Voulant mettre à plat la doc, et avoir à maintenir dans le moins d'endroits possibles les évolutions, je me pose la question suivante:
Est-il possible, à la génération de la Javadoc (par ex.) d'executer des tests (ca, ca me semble jouable) mais surtout, si ces tests passent, des les inclure dans la doc généré? Si c'est possible, connaissez-vous des solutions?

A priori, je vois plutot une solution avec des annotations:

Code java :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
 
/**
 * Contrainte d'égalité, assure que v0 = v1
 * ...
 * @testToIntegrate : com.ppc.Exemples.exempleEQ()
 */
public Constraint eq(Variable v0, Variable v1){
//...
}

A la génération du code, on exectuerai (ou compilerai simplement) la méthode exempleEQ contenu dans la classe Exemples, et si ca passe, on l'inclu dans la doc.

Mais peut-être existe-t-il d'autres solutions?

Merci d'avance,

Charles

[tchize_]

Petite question comme çà, est-ce que des outils comme maven, qui permettent de créer un site web contenant les résultat de tes unit test, la javadoc, des rapports d'analyse de code, etc, ne pourraient pas convenir à ta demande? C'est un peu long à mettre en place mais çà permet d'intégrer tout le processus de développement. Pour ce qui est de la javadoc, les outils javadoc (sans en connaitre les détails moi meme) founissent des options d'extensibilité. J'ai vu comme çà des javadoc où l'on réalisait en meme temps le diagramme uml de la classe ou du package. Mais de là à faire tourner des unit test en meme temps et inclure conditionnelement .... Je serais plutot chaud d'utiliser des trucs comem maven et de faire un lien vers la source de l'exemple (via les docs xref de maven). Parce que, honnêtement, faire de la javadoc et lancer des units tests, c'est des domaines totalement différents....

[adiGuba]

Salut,

A priori, je vois plutot une solution avec des annotations:

Dans le cas présent il ne s'agit pas d'annotation mais de taglet.
Les annotations sont présent directement dans le code, tandis que les taglets font partis des commentaires JavaDoc.


Mais la bonne nouvelle c'est que cela doit être possible : l'API de JavaDoc met en place une API Taglet, qui permet de les traiter directement lors de la génération de la JavaDoc !


Concrètement : tu dois implémenter une interface Taglet qui prendra en compte ton @testToIntegrate. Lors de la génération de la javadoc, une méthode toString(Tag) de ton taglet sera exécutée avec les infos du tag. A toi d'exécuter le test et de générer le code HTML qui va bien, et qui sera inséré dans la javadoc

Plus d'info : Taglet Overview

Tu y trouveras l'exemple d'un @todo qui se contente d'affiche une information souligné en jaune


a++

[Carlito_superheros]

Merci à vous deux, je vais me pencher sur vos réponses.

Charles