Cara menjaga agar contoh kode di javadocs diperbarui

Saya sedang mengerjakan perpustakaan kecil yang menyediakan implementasi metrik string dasar yang terkenal. Sebagian besar untuk pendidikan saya sendiri. Jadi pengembangan terjadi setiap kali saya punya sedikit waktu luang.

Karena ini saya telah mengotomatisasi sebagian besar proses sehingga saya dapat merilis versi sesering saya mengerjakannya tanpa terlalu banyak usaha. Namun mempertahankan dokumen Java masih menjadi beban karena termasuk contoh.

Ketika API berkembang, saya secara manual harus memeriksa setiap contoh berulang kali. Apakah ada cara yang lebih baik untuk melakukan ini?

Saya telah mempertimbangkan untuk memindahkan dokumentasi dan contoh ke proyek yang terpisah (mis. Tutorial Caliper ) sehingga dapat difaktorkan ulang dan dikompilasi bersama dengan kode reguler. Namun itu memindahkan dokumentasi dari kelas.

Jadi ya. Saya ingin memiliki kue dan memakannya juga. : 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>

Jika di atas terlalu abstrak. Ini adalah contoh dokumentasi. Saat ini saya menambahkan konstruktor statis seperti yang disarankan oleh Java Efektif misalnya Tokenizers.createQGram(2)sambil mendepresiasi metode konstruktor. Setiap kali saya melakukan sesuatu seperti ini, saya harus memperbarui kode contoh di atas dan memeriksa apakah masih berfungsi.

Ini mungkin tidak menjawab pertanyaan Anda - tergantung pada seberapa banyak 'persyaratan' untuk memiliki contoh-contoh ini dalam dokumentasi Anda.

Mungkin Anda bisa melakukan sudut yang berbeda: Berikan contoh dalam tes JUnit Anda. (Mungkin bahkan paket seperti com.examples) Masalah dengan kode dalam komentar adalah bahwa IDE Anda akan mengabaikannya, sebagian besar. Tetapi IDE Anda akan memvalidasi kode dalam tes JUnit Anda. Dengan melakukan ini, Anda memastikan contoh kode 'benar' - tes tidak akan dikompilasi atau gagal jika Anda belum memperbaruinya.

Saya bukan penyihir dengan Javadocs, tetapi mungkin ada cara untuk menautkan dokumentasi file sumber Anda ke file JUnit dengan kode contoh di dalamnya. Tapi aku benar-benar tidak tahu harus mulai dari mana. Googling sepintas menunjukkan saya @seetag . Saya mengujinya dalam suatu proyek tetapi belum mengujinya di javadoc yang sebenarnya setelah dihasilkan.

Ini pasti akan memerlukan sedikit riset di muka, tapi saya benar-benar berpikir Anda akan lebih baik dalam jangka panjang jika contoh kode Anda benar-benar sedang dikompilasi.

Sebagai sasaran, Anda juga bisa menambahkan cakupan kode saat menjalankan contoh JUnit Anda. Dengan cara ini Anda akan tahu sekilas berapa banyak basis kode Anda dicakup oleh contoh-contoh Anda.