はじめに
JavaのAPIドキュメントに数式を埋め込みたくてDoxygenを長年使ってきたが、JavadocでもMathJaxを使って数式を埋め込めるようなので試してみた。
環境
- Java 1.8
- Apache Maven 3.3.0
- Apache Maven Javadoc Plugin 3.0.0
POMの設定
Apache Maven Javadoc Pluginで、ヘッダにMathJaxのCDNを追加すればJavadocのAPIドキュメントに数式を埋め込めるようになるはずだが、コメントにJavaScriptは埋め込んでは駄目とのエラーメッセージ。どうやらJava 8になってから厳しくなったらしい。そこで、<additionalparam>で--allow-script-in-commentsをオプション指定するもうまくいかない。さらに調べてみると、Javadoc Plugin 3.0.0ではオプション指定が<additionalparam>から<additionalOptions>に変更されていた。ついでに、Markdownが使えるようにMarkdownが使えるDocletを追加した。最終的なPOMファイルの設定は以下の通り。（<build><plugins>...</plugins></build>）
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.0.0</version>
<configuration>
<additionalOptions>
<additionalOption>--allow-script-in-comments</additionalOption>
</additionalOptions>
<header>
<![CDATA[
<script type="text/javascript"
src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
]]>
</header>
<doclet>ch.raffael.mddoclet.MarkdownDoclet</doclet>
<docletArtifact>
<groupId>ch.raffael.markdown-doclet</groupId>
<artifactId>markdown-doclet</artifactId>
<version>1.4</version>
</docletArtifact>
<useStandardDocletOptions>true</useStandardDocletOptions>
数式のサンプル
試しに、以下の数式サンプルをjavadocに埋め込んでみた。
/**
*
* @author hoge
*
* MathJax Samples
* ===
*
* This javadoc API document is configured to use MathJax's CommonHTML mode with
* web fonts to display the equations, which produces uniform layout and
* typesetting across browsers. But MathJax can also be configured to use
* HTML-CSS (for legacy browsers), SVG, and native MathML rendering when
* available in a browser. You can try the various output modes using the
* MathJax context Menu (which you access by ctrl+clicking / alt-clicking an
* equation) or the button below.
*
* - The Quadratic Formula
* $$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
*
* - Cauchy's Integral Formula
*
* $$ f(a) = \frac{1}{2\pi i} \oint\frac{f(z)}{z-a}dz $$
*
* - Double angle formula for Cosines
*
* $$ \cos(\theta+\phi)=\cos(\theta)\cos(\phi)−\sin(\theta)\sin(\phi) $$
*
*
*/
public class Main {
}
下図は、上記のJavadocから自動生成したAPIドキュメント。綺麗に数式が表示されている。わざわざDoxygenを使わなくてもJavadocで数式を埋め込めることを確認できた。
まとめ
APIドキュメントに数式を埋め込みたくてDoxygenを使ってきたが、Javadocでも綺麗な数式を扱えることを確認できた。Javadocは、JavaのソースコードからHTML形式のAPI仕様書を生成する標準ツールなので、DoxygenからJavadocへ移行できるのはメリットが大きい。Doxygenでは、Javadocスタイルを採用していたので、移行もそれほど難しくなさそうである。今回、新しく取り入れたMarkdownが使えるDocletはUMLの自動生成も可能なのでAPIドキュメントの表現が更に多彩になることが期待される。