Come mantenere aggiornati gli esempi di codice in javadoc

9

Sto lavorando su una piccola libreria che fornisce implementazioni di metriche di base e ben note. Principalmente per la mia educazione. Quindi lo sviluppo accade 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 problema perché include esempi.

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

Ho preso in considerazione di spostare la documentazione e gli esempi in un progetto separato (ad es. Esercitazione su Caliper ) in modo che possa essere rielaborato e compilato insieme al codice normale. Tuttavia ciò sposta la documentazione lontano dalla classe di cui tratta.

Quindi sì. 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 es. Tokenizers.createQGram(2) durante il deprezzamento del metodo del costruttore. Ogni volta che faccio qualcosa di simile, dovrei aggiornare il codice di esempio sopra e controllare se funziona ancora.

    
posta mpkorstanje 10.08.2015 - 17:30
fonte

1 risposta

8

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

Forse potresti fare un'angolazione 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, si garantisce che gli esempi di codice siano "corretti": i test non verranno compilati o semplicemente falliranno se non li si è aggiornati.

Non sono un wizard con Javadocs, ma potrebbe esserci un modo per collegare la documentazione del file sorgente al file JUnit con il codice di esempio al suo interno. Però non saprei proprio da dove cominciare. Un rapido googling mi ha mostrato il tag @see . L'ho provato in un progetto ma non l'ho testato in un javadoc dopo che è stato generato.

Questo richiederebbe sicuramente un po 'di ricerca in anticipo, ma penso davvero che staresti meglio a lungo andare se i tuoi esempi di codice fossero effettivamente compilati.

Come obiettivo di estensione, puoi anche aggiungere la copertura del codice durante l'esecuzione degli esempi di JUnit. In questo modo sapresti a colpo d'occhio quanto del tuo codice base è coperto dai tuoi esempi.

    
risposta data 10.08.2015 - 20:51
fonte

Leggi altre domande sui tag