Introduction

I've been using Doxygen for many years because I wanted to embed formulas in Java API documentation, but I tried it because Javadoc also seems to be able to embed formulas using MathJax.

environment

Java 1.8
Apache Maven 3.3.0
Apache Maven Javadoc Plugin 3.0.0

POM settings

With Apache Maven Javadoc Plugin, if you add MathJax CDN to the header, you should be able to embed formulas in Javadoc API documentation, but an error message saying that JavaScript cannot be embedded in comments. Apparently it has become stricter since Java 8. Therefore, specifying --allow-script-in-comments as an option with ``` `` does not work. Upon further investigation, Javadoc Plugin 3.0.0 changed the option specification from ```` to ````. By the way, I added a Doclet that can use Markdown so that Markdown can be used. The final POM file settings are as follows. (`` ... </ 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>

Formula sample

As a test, I embedded the following formula sample in 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 {
    
}

The figure below is an API document automatically generated from the above Javadoc. The formula is displayed neatly. I was able to confirm that I could embed formulas in Javadoc without having to bother to use Doxygen.

Summary

I've been using Doxygen to embed formulas in API documentation, but I've confirmed that Javadoc can handle pretty formulas as well. Javadoc is a standard tool that generates HTML-format API specifications from Java source code, so it is a great advantage to be able to migrate from Doxygen to Javadoc. Doxygen used the Javadoc style, so migration doesn't seem to be that difficult either. This time, the newly introduced Doclet that can use Markdown can also automatically generate UML, so it is expected that the expression of API documents will be more diverse.

Reference material

https://github.com/Abnaxos/markdown-doclet
http://docs.mathjax.org/en/latest/index.html#
http://www.zverovich.net/2012/01/14/beautiful-math-in-javadoc.html
https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html
https://stackoverflow.com/questions/2784183/what-does-cdata-in-xml-mean