Javadocを楽にする



これまで極めて適当にしかJavadocを書いてこなかったのだが、そろそろきちんと書くようにしたいと思うのだが、いかんせんあまりに資料が少なすぎるし、正しい書き方や正しい処理方法(ソースからのHTML生成)の方法がわからない。ここでは少しずつまとめていく。

Javadoc以外の選択肢はあるのか?

その前にJavadoc以外の選択肢はといえば、当然Markdownである。つまり、ソースコードのコメントとしてMarkdownを書いてしまい。それをMarkdown用のDocletで処理させてしまうというやり方があるらしい。

素晴らしいと思うのだが、この採用は見送った。なぜなら、ソースからの
HTML生成だけではなく、Eclipse IDE環境での自動チェックが欲しいからである。

そうでないと、Javadocの吐き出したエラーを見ながらいちいち修正していかなくてはいけない、非効率的だ。

Eclipseでのチェック

Compiler設定でのチェック

以下の場所に設定がある。

しかし、バグなのか私の書き方が悪いのか、package-info.javaからのリンクが見つからないと言われる。例えば、

/**
 * {@link Sample}というクラスは。。。
 */

とまるで同じパッケージ内のクラスを参照しているのに、「見つからない」と言ってくる。Javadocでの処理は正常である。

CheckStyle

CheckStyleというEclipseプラグインがあるのだが、これはJavadocだけではなく、Java全体のスタイルをチェックするものようだが、あまりに厳しすぎてこれまたやっていられない。何とかJavadocだけを対象とさせるよう設定するつもりだ。

JavaDoc中でのコードの記述

特に困るのがJavadoc中にコード例をどう書くかだ。大小記号やアットマークはそのまま書けないので、何も考えないと以下のように面倒なことになる。

※エスケープが面倒なので全角で記述している。

@Path("path")
public int test(int a, int b) {
  return a < b;
}

これは<pre>、<code>、{@code}、{@literal}をうまく組み合わせて使えば何とかなるようだ。しかし、何ともならない部分もある。

原則:どうやっても@はそのまま記述できない

先に示したように「&#064;」と記述するか、あるいは「{@literal @}」などと記述する必要がある。

原則:pre、codeで囲む

基本的にはpreの中にcodeを入れるのだが、二通りある。

XMLなど、大小記号が多い場合には{@code}を使う。この中では大小記号をエスケープせずに使える。

 * <pre>
 * {@code
 * <xml>
 * </xml>
 * }
 * </pre>

Javaコードなど、中括弧の多い場合には、<code>を使う。この中では中括弧をエスケープせずに使える。

 * <pre>
 * <code>
 * {@literal @}Path("/path")
 * public int test() {
 * }
 * </code>
 * </pre>

面倒だが、このような方法しか見つからなかった。もっと良い方法もあるかもしれない。

Javadoc中での画像の取り込み

これはあちこちに記述があるが、例えばSample.javaに画像を貼りたい場合には、そのパッケージの中にdoc-filesというフォルダ(パッケージ)を作成し、その中に画像を入れるのだそうだ。

 * <img alt="test" src="doc-files/test.png">

※ちなみに、altを入れないとjavadocが通らなかった。どこかにスイッチがあるかもしれない。

しかし、「doc-files」と名前の指定があるからには、Javaのコンパイル結果からは無視されるのだろうと思いきや、全く無視されておらず、このJavadoc用の画像も製品に紛れ込むことになってしまう。

何かしらの方法で無視させるようにしないといけない。Gradle上でコンパイルしたのだが、何かのスイッチがあるかもしれない。

ちなみに、Javaのコンパイルからは排除されないのだから、パッケージ名称は何でも良いだろうと試しに「images」にしてみると、

 * <img alt="test" src="images/test.png">

完全に無視された。生成されたjavadocには画像ファイルがコピーされていない。