introduction

J'utilise Doxygen depuis de nombreuses années parce que je voulais intégrer des formules dans la documentation API de Java, mais Javadoc semble également être capable d'incorporer des formules à l'aide de MathJax, alors je l'ai essayé.

environnement

Java 1.8
Apache Maven 3.3.0
Apache Maven Javadoc Plugin 3.0.0

Paramètres POM

Avec Apache Maven Javadoc Plugin, si vous ajoutez le CDN de MathJax à l'en-tête, vous devriez pouvoir incorporer des formules dans la documentation de l'API Javadoc, mais un message d'erreur indiquant que vous ne pouvez pas incorporer JavaScript dans les commentaires. Apparemment, il est devenu plus strict depuis Java 8. Par conséquent, spécifier --allow-script-in-comments``` comme option avec '' ne fonctionne pas. Après une enquête plus approfondie, Javadoc Plugin 3.0.0 a changé la spécification de l'option de '' à <additionalOptions> ''. En passant, j'ai ajouté un Doclet qui peut utiliser Markdown afin que Markdown puisse être utilisé. Les paramètres finaux du fichier POM sont les suivants. ( ... </ 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>

Échantillon de formule

En guise de test, j'ai intégré l'exemple de formule suivant dans 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 {
    
}

La figure ci-dessous est un document API généré automatiquement à partir du Javadoc ci-dessus. La formule s'affiche proprement. J'ai pu confirmer que je pouvais intégrer des formules dans Javadoc sans avoir à me soucier d'utiliser Doxygen.

Résumé

J'utilise Doxygen pour intégrer des formules dans la documentation de l'API, mais j'ai confirmé que Javadoc pouvait également gérer de jolies formules. Javadoc est un outil standard qui génère des spécifications d'API HTML à partir du code source Java, c'est donc un grand avantage de pouvoir migrer de Doxygen vers Javadoc. Doxygen a utilisé le style Javadoc, donc la migration ne semble pas non plus si difficile. Le Doclet nouvellement introduit qui peut utiliser Markdown peut également générer automatiquement UML, donc on s'attend à ce que l'expression des documents API soit plus diversifiée.

Matériel de référence

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