Javadoc Plug-in

Javadoc is a tool that parses the declarations and documentation comments in a set of source files and produces a set of HTML pages describing the classes, interfaces, constructors, methods, and fields.

Javadoc supports doclets used to customize Javadoc output. A doclet is a program written with the Doclet API that specifies the content and format of the output to be generated by the Javadoc tool.

A library exists to preprocess Javadoc comments from Java source code to a XML document. It can be downloaded here. This DITA-OT plugin processes a JavaDoc XML and the converts it to DITA allowing the generation of PDF API documentation.

/**
 * Effector is the interface for Casbin effectors.
 */
public interface Effector {
    /**
     * mergeEffects merges all matching results collected by the enforcer into a single decision.
     *
     * @param expr the expression of [policy_effect].
     * @param effects the effects of all matched rules.
     * @param results the matcher results of all matched rules.
     * @return the final effect.
     */
    boolean mergeEffects(String expr, Effect[] effects, float[] results);
}

Run the plug-in installation commands:

dita install https://github.com/doctales/org.doctales.xmltask/archive/master.zip
dita install https://github.com/jason-fox/fox.jason.passthrough/archive/master.zip
dita install https://github.com/jason-fox/fox.jason.passthrough.javadoc/archive/master.zip

The dita command line tool requires no additional configuration.

If you are using Maven you can generate XML-based Javadoc by adding the following plug-in to your pom.xml. Javadoc will be generated using the mvnpackage command.

<project>
  ...
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <executions>
      <execution>
        <id>xml-doclet</id>
        <phase>prepare-package</phase>
        <goals>
          <goal>javadoc</goal>
        </goals>
        <configuration>
          <doclet>com.github.markusbernhardt.xmldoclet.XmlDoclet</doclet>
          <additionalparam>-d ${project.build.directory} -filename ${project.artifactId}-${project.version}-javadoc.xml</additionalparam>
          <useStandardDocletOptions>false</useStandardDocletOptions>
          <docletArtifact>
            <groupId>com.github.markusbernhardt</groupId>
            <artifactId>xml-doclet</artifactId>
            <version>1.0.5</version>
          </docletArtifact>
        </configuration>
    </execution>
    </executions>
  </plugin>
  ...
</project>

If you are not using Maven, you can use the jar-with-dependencies, which contains all required libraries.

javadoc -doclet com.github.markusbernhardt.xmldoclet.XmlDoclet \
     -docletpath xml-doclet-1.0.5-jar-with-dependencies.jar \
   [Javadoc- and XmlDoclet-Options]

Once the source XML has been created, add it to the <map> and mark it for Javadoc processing, by labelling the <topicref> with @format="javadoc" within the <map> as shown:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN" "bookmap.dtd">
<bookmap>
    ...etc
    <appendices toc="yes" print="yes">
      <topicmeta>
        <navtitle>Appendices</navtitle>
      </topicmeta>
      <appendix format="dita" href="topic.dita">
        <topicref format="javadoc" type="topic" href="javadoc.xml"/>
      </appendix>
   </appendices>
</bookmap>

The additional file will be converted to a *.dita file and will be added to the build job without further processing. Unless overridden, the @navtitle of the included <topic> will be the same as root name of the file. Any underscores in the filename will be replaced by spaces in title.