Javadoc の package.html をパースできない不具合
Javadoc は package.html という HTML をパッケージに配置しておけば、パッケージサマリーページとして取り込んでくれる。
今まで数千の package.html を生成し、数十万行にわたるドキュメントを書いてきた私ですら、本日初めて遭遇する Javadoc のバグが見つかった。
Javadoc は package.html の body タグの内容を取り込むわけだが、以下の環境で Javadoc の生成に失敗してエラーが発生する。
<body>あ</body>
- javadoc コマンドは以下の通り
javadoc -d foo -encoding Shift_JIS -charset UTF-8 foo/*.java ソースファイル foo\Foo.java を読み込んでいます... Javadoc 情報を構築しています... 標準 Doclet バージョン 1.6.0_39 全パッケージとクラスの階層ツリーを作成しています... foo\Foo.html の生成 foo\package-frame.html の生成 foo\package-summary.html の生成 foo\package.html: エラー - HTML ファイルに body の閉じタグがありません。 foo\package-tree.html の生成 foo\constant-values.html の生成 全パッケージとクラスのインデックスを作成しています... foo\overview-tree.html の生成 foo\index-all.html の生成 foo\deprecated-list.html の生成 全クラスのインデックスを作成しています... foo\allclasses-frame.html の生成 foo\allclasses-noframe.html の生成 foo\index.html の生成 foo\help-doc.html の生成 foo\stylesheet.css の生成 エラー 1 個
ソースコードは Shift_JIS なんだけど、Javadoc は UTF-8 で出力したい、というねじまがった運用の悲劇と言えよう。なお、package.html を以下のように改行するだけで、とりあえず body の閉じタグが見つけられない、という Javadoc のバグは回避できる。
<body>あ </body>
余談だが JDK 1.5 以降は、package-info.java という Java ソースコードが package.html の代用として使用できる。この package-info.java、メリットばかりということはない。
