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}をうまく組み合わせて使えば何とかなるようだ。しかし、何ともならない部分もある。
原則：どうやっても@はそのまま記述できない
先に示したように「＆＃０６４；」と記述するか、あるいは「{@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には画像ファイルがコピーされていない。