Comment garder à jour les exemples de code dans javadocs

Je travaille sur une petite bibliothèque qui fournit des implémentations de métriques de chaîne de base bien connues. Surtout pour ma propre éducation. Le développement se produit donc chaque fois que j'ai un peu de temps libre.

Pour cette raison, j'ai automatisé la plupart des processus afin que je puisse publier une version aussi souvent que j'y travaille sans trop d'effort. Cependant, la maintenance du document Java reste un fardeau car il comprend des exemples.

Au fur et à mesure que l'API évolue, je dois manuellement vérifier chaque exemple encore et encore. Y a-t-il une meilleure manière de faire cela?

J'ai envisagé de déplacer la documentation et les exemples dans un projet distinct (par exemple Caliper Tutorial ) afin de pouvoir le refactoriser et le compiler avec le code normal. Cependant, cela éloigne la documentation de la classe dont il s'agit.

Donc voilà. J'aimerais avoir mon gâteau et le manger aussi. :RÉ

 * <h2>Tokenization</h2>
 * 
 * Tokenization cuts up a string into tokens e.g.
 * <code>chilperic ii son of childeric ii</code> is tokenized into
 * <code>[chilperic, ii, son, of,
 * childeric, ii]</code>. Tokenization can also be done repeatedly by tokenizing
 * the individual tokens e.g.
 * <code>[ch,hi,il,il,lp,pe,er,ri,ic, ii, so,on, of, ch,hi,il,ld,de,er,ri,ic, ii]</code>
 * <p>
 * 
 * <pre>
 * <code>
 * {@code
 *  return new StringMetricBuilder()
 *          .with(new SimonWhite<String>())
 *          .tokenize(new Whitespace())
 *          .tokenize(new QGram(2))
 *          .build();
 * }
 * </code>
 * </pre>
 * 
 * <p>

Si ce qui précède est trop abstrait. Ceci est un exemple de documentation. Actuellement, j'ajoute des constructeurs statiques comme conseillé par Effective Java, par exemple Tokenizers.createQGram(2)tout en dépréciant la méthode des constructeurs. Chaque fois que je fais quelque chose comme ça, je dois mettre à jour l'exemple de code ci-dessus et vérifier si cela fonctionne toujours.

Cela pourrait ne pas répondre à votre question - selon la quantité d '«exigence» que d'avoir ces exemples dans votre documentation.

Vous pourriez peut-être faire un angle différent: fournissez des exemples dans vos tests JUnit. (Peut-être même un package comme com.examples) Le problème avec le code dans les commentaires est que votre IDE va ​​l'ignorer, pour la plupart. Mais votre IDE validera le code dans vos tests JUnit. En faisant cela, vous vous assurez que les exemples de code sont «corrects» - les tests ne seront pas compilés ou échoueront simplement si vous ne les avez pas mis à jour.

Je ne suis pas un assistant avec Javadocs, mais il pourrait y avoir un moyen de lier la documentation de votre fichier source au fichier JUnit avec l'exemple de code qu'il contient. Je ne sais vraiment pas par où commencer. Une recherche rapide sur Google m'a montré l' @seeétiquette . Je l'ai testé dans un projet, mais je ne l'ai pas testé dans un javadoc réel après sa génération.

Cela nécessiterait certainement un peu de recherche préalable, mais je pense vraiment que vous feriez mieux à long terme si vos exemples de code étaient réellement compilés.

Comme objectif d'extension, vous pouvez également ajouter une couverture de code lors de l'exécution de vos exemples JUnit. De cette façon, vous sauriez en un coup d'œil quelle proportion de votre base de code est couverte par vos exemples.