Cómo mantener actualizados los ejemplos de código en javadocs

Estoy trabajando en una pequeña biblioteca que proporciona implementaciones de métricas de cadena básicas y bien conocidas. Principalmente para mi propia educación. Entonces, el desarrollo ocurre cada vez que tengo un poco de tiempo libre.

Debido a esto, he automatizado la mayoría de los procesos para poder lanzar una versión tan a menudo como trabajo en ella sin demasiado esfuerzo. Sin embargo, mantener el documento de Java sigue siendo una carga porque incluye ejemplos.

A medida que la API evoluciona, tengo que verificar manualmente cada ejemplo una y otra vez. ¿Hay una mejor manera de hacer esto?

He considerado trasladar la documentación y los ejemplos a un proyecto separado (por ejemplo, Caliper Tutorial ) para que pueda ser refactorizado y compilado junto con el código regular. Sin embargo, eso aleja la documentación de la clase de la que se trata.

Así que sí. Me gustaría tener mi pastel y comerlo también. :RE

 * <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 lo anterior es demasiado abstracto. Esta es una muestra de documentación. Actualmente estoy agregando constructores estáticos como lo aconseja Effective Java, por ejemplo, Tokenizers.createQGram(2)mientras deprecia el método de construcción. Cada vez que hago algo como esto, tengo que actualizar el código de ejemplo anterior y verificar si aún funciona.

Es posible que esto no responda a su pregunta, dependiendo de qué tan 'requisito' sea tener estos ejemplos en su documentación.

Quizás podría hacer un ángulo diferente: proporcione ejemplos en sus pruebas JUnit. (Quizás incluso un paquete como com.examples) El problema con el código en los comentarios es que su IDE lo ignorará, en su mayor parte. Pero su IDE validará el código en sus pruebas JUnit. Al hacer esto, se asegura de que los ejemplos de código sean 'correctos': las pruebas no se compilarán o simplemente fallarán si no las ha actualizado.

No soy un asistente con Javadocs, pero podría haber una manera de vincular la documentación de su archivo fuente al archivo JUnit con el código de ejemplo. Sin embargo, realmente no sabría por dónde empezar en esto. Un google superficial me mostró la @seeetiqueta . Lo probé en un proyecto pero no lo he probado en un javadoc real después de que se generó.

Definitivamente, esto requeriría un poco de investigación por adelantado, pero realmente creo que sería mejor a largo plazo si sus ejemplos de código realmente se estuvieran compilando.

Como objetivo adicional, también puede agregar cobertura de código al ejecutar sus ejemplos JUnit. De esta manera, sabría de un vistazo cuánto de su código base está cubierto por sus ejemplos.