Einführung

Ich verwende Doxygen seit vielen Jahren, weil ich Formeln in die API-Dokumentation von Java einbetten wollte, aber Javadoc scheint auch in der Lage zu sein, Formeln mit MathJax einzubetten, also habe ich es versucht.

Umgebung

Java 1.8
Apache Maven 3.3.0
Apache Maven Javadoc Plugin 3.0.0

POM-Einstellungen

Wenn Sie mit dem Apache Maven Javadoc-Plugin das CDN von MathJax zum Header hinzufügen, sollten Sie in der Lage sein, Formeln in die API-Dokumentation von Javadoc einzubetten, aber eine Fehlermeldung besagt, dass Sie JavaScript nicht in Kommentare einbetten können. Anscheinend ist es seit Java 8 strenger geworden. Daher funktioniert es nicht, `--allow-script-in-comment``` als Option mit` `anzugeben. Nach weiteren Untersuchungen änderte das Javadoc Plugin 3.0.0 die Optionsspezifikation von "<additionalparam>" in "<additionalOptions>". Übrigens habe ich ein Doclet hinzugefügt, das Markdown verwenden kann, damit Markdown verwendet werden kann. Die endgültigen Einstellungen für die POM-Datei lauten wie folgt. ( <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>

Formelprobe

Als Test habe ich das folgende Formelbeispiel in Javadoc eingebettet.

/**
 * 
 * @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 {
    
}

Die folgende Abbildung ist ein API-Dokument, das automatisch aus dem obigen Javadoc generiert wird. Die Formel wird übersichtlich angezeigt. Ich konnte bestätigen, dass ich Formeln in Javadoc einbetten konnte, ohne mir die Mühe machen zu müssen, Doxygen zu verwenden.

Zusammenfassung

Ich habe Doxygen verwendet, um Formeln in die API-Dokumentation einzubetten, aber ich habe bestätigt, dass Javadoc auch hübsche Formeln verarbeiten kann. Javadoc ist ein Standardtool, das HTML-API-Spezifikationen aus Java-Quellcode generiert. Daher ist es ein großer Vorteil, von Doxygen nach Javadoc migrieren zu können. Doxygen verwendete den Javadoc-Stil, daher scheint die Migration auch nicht so schwierig zu sein. Dieses Mal kann das neu eingeführte Doclet, das Markdown verwenden kann, auch automatisch UML generieren. Daher wird erwartet, dass der Ausdruck von API-Dokumenten vielfältiger wird.

Referenzmaterial

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