Come mantenere aggiornati gli esempi di codice in javadocs

Sto lavorando a una piccola libreria che fornisce implementazioni di metriche di stringa di base ben note. Principalmente per la mia educazione. Quindi lo sviluppo avviene ogni volta che ho un po 'di tempo libero.

Per questo motivo ho automatizzato la maggior parte dei processi in modo da poter rilasciare una versione tutte le volte che ci lavoro senza troppi sforzi. Tuttavia, mantenere il documento Java è ancora un peso perché include esempi.

Man mano che l'API si evolve, devo controllare manualmente ogni esempio ancora e ancora. C'è un modo migliore per farlo?

Ho preso in considerazione l'idea di spostare la documentazione e gli esempi in un progetto separato (ad es. Caliper Tutorial ) in modo che possa essere rielaborato e compilato insieme al codice normale. Tuttavia, ciò allontana la documentazione dalla classe di cui si tratta.

Quindi si Mi piacerebbe avere la mia torta e mangiarla anch'io. : D

 * <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>

Se quanto sopra è troppo astratto. Questo è un esempio di documentazione. Attualmente sto aggiungendo costruttori statici come consigliato da Effective Java, ad esempio Tokenizers.createQGram(2)deprezzando il metodo del costruttore. Ogni volta che faccio qualcosa del genere, dovrei aggiornare il codice di esempio sopra e verificare se funziona ancora.

Questo potrebbe non rispondere alla tua domanda, a seconda di quanto "requisito" sia avere questi esempi nella tua documentazione.

Forse potresti fare una prospettiva diversa: fornisci esempi nei tuoi test JUnit. (Forse anche un pacchetto come com.examples) Il problema con il codice nei commenti è che il tuo IDE lo ignorerà, per la maggior parte. Ma il tuo IDE convaliderà il codice nei tuoi test JUnit. In questo modo, ti assicuri che gli esempi di codice siano "corretti": i test non verranno compilati o semplicemente falliranno se non li hai aggiornati.

Non sono un mago con Javadocs, ma potrebbe esserci un modo per collegare la documentazione del file sorgente al file JUnit con il codice di esempio in esso. Non saprei davvero da dove cominciare. Un veloce googling mi mostrò il @seetag . L'ho testato in un progetto ma non l'ho testato in un vero javadoc dopo che è stato generato.

Ciò richiederebbe sicuramente un po 'di ricerca iniziale, ma penso davvero che a lungo andare sarebbe meglio se i tuoi esempi di codice fossero effettivamente compilati.

Come obiettivo estensivo, puoi anche aggiungere la copertura del codice quando esegui i tuoi esempi JUnit. In questo modo sapresti a colpo d'occhio quanta parte della tua base di codice è coperta dai tuoi esempi.