This is a DITA-OT Plug-in used to auto-create valid DITA-based JavaDoc documentation. The initial source of the documentation can be generated directly using the JavaDoc XML Doclet. The XML file can be added to the source and processed as if it had been written in DITA.
Table of Contents
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);
}
The DITA-OT JavaDoc plug-in has been tested against DITA-OT 4.x. The plugin requires the XSLT 3.0 support found in the Saxon9.8HE library, so the mimimum DITA-OT version is therefore 3.3. It is recommended that you upgrade to the latest version.
The DITA-OT JavaDoc plug-in is a file reader for the DITA Open Toolkit.
-
Full installation instructions for downloading DITA-OT can be found here.
- Download the
dita-ot-4.2.zip
package from the project website at dita-ot.org/download - Extract the contents of the package to the directory where you want to install DITA-OT.
- Optional: Add the absolute path for the
bin
directory to the PATH system variable.
This defines the necessary environment variable to run the
dita
command from the command line. - Download the
curl -LO https://github.com/dita-ot/dita-ot/releases/download/4.2/dita-ot-4.2.zip
unzip -q dita-ot-4.2.zip
rm dita-ot-4.2.zip
- Run the plug-in installation commands:
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 mvn package
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 *.ditamap
and mark it for JavaDoc processing, by labelling it
with format="javadoc"
within the *.ditamap
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.
Apache 2.0 © 2019 - 2024 Jason Fox