Javadocに数式を埋め込んでみた


はじめに

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ドキュメントの表現が更に多彩になることが期待される。

参考資料