web-dev-qa-db-ja.com

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

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

このため、ほとんどのプロセスを自動化したので、あまり労力をかけずに、作業するたびにバージョンをリリースできます。ただし、Java docを維持することは、例が含まれているため、依然として負担になります。

APIが進化するにつれ、各例を何度も手動で確認する必要があります。これを行うためのより良い方法はありますか？

ドキュメントと例を別のプロジェクト（例： Caliper Tutorial ）に移動して、通常のコードと一緒にリファクタリングおよびコンパイルできるようにすることを検討しました。しかし、それはドキュメントをそれが関係しているクラスから遠ざけます。

そうそう。ケーキも食べたいです。 ：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 eg Tokenizers.createQGram(2)のアドバイスに従って、コンストラクターメソッドを減価償却しながら静的コンストラクターを追加しています。このようなことを行うたびに、を更新する必要があります。上記のコード例を実行して、それがまだ機能するかどうかを確認してください。

javadocumentationjavadocs
9
M.P. Korstanje

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

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

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

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

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

8
Shaz