javadocsのコード例を最新に保つ方法

私は、基本的なよく知られている文字列メトリックの実装を提供する小さなライブラリに取り組んでいます。主に私自身の教育のために。ですから、少し時間があるときに開発が行われます。

このため、私はほとんどのプロセスを自動化しているので、バージョンをリリースするのに、手間をかけずに頻繁に行うことができます。ただし、例が含まれているため、Java docの保守は依然として負担です。

APIが進化するにつれ、各例を手動で繰り返し確認する必要があります。これを行うより良い方法はありますか？

ドキュメントと例を別のプロジェクト（Caliperチュートリアルなど）に移動することを検討したので、通常のコードと一緒にリファクタリングしてコンパイルできます。ただし、これにより、ドキュメントが目的のクラスから移動します。

そうそう。ケーキも食べてみたいです。：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>

上記の場合は抽象的すぎます。これはドキュメントのサンプルです。現在、Effective Javaのアドバイスに従って静的コンストラクターを追加していますTokenizers.createQGram(2)。たとえば、コンストラクターメソッドの価値を下げています。このようなことをするたびに、上の例のコードを更新して、それがまだ機能するかどうかを確認する必要があります。

これはあなたの質問に答えないかもしれません-あなたのドキュメンテーションにこれらの例を含めることがどれだけの「要件」に依存するかによって。

おそらく、別の角度から行うこともできます。JUnitテストで例を提供してください。（おそらくcom.examplesのようなパッケージでも）コメント内のコードの問題は、IDEがほとんどの場合無視することです。しかし、IDEはJUnitテストのコードを検証します。これを行うことにより、コード例が「正しい」ことを確認します。テストをコンパイルしなかったり、更新しなかった場合、テストは単に失敗したりします。

私はJavadocを使用するウィザードではありませんが、ソースファイルのドキュメントをサンプルコードを含むJUnitファイルにリンクする方法があるかもしれません。しかし、これからどこから始めればよいのか本当にわかりません。大まかなグーグルで@seeタグが表示されました。プロジェクトでテストしましたが、生成後の実際のjavadocではテストしていません。

これには間違いなく少し前もって調査する必要がありますが、実際にコード例が実際にコンパイルされている場合は、長期的に見たほうがいいと思います。

ストレッチゴールとして、JUnitサンプルを実行するときにコードカバレッジを追加することもできます。これにより、コードベースのどの程度がサンプルでカバーされているかが一目でわかります。