JarCastingAsciidoclet & Diagram for JDK 11
Asciidoclet is a Javadoc Doclet based on Asciidoctor that lets you write Javadoc in the AsciiDoc syntax.
However, Java 9 completely changed the internal JavaDoc APIs in incompatible ways, making the existing Asciidoclet unusable from Java 9 onward. Chris Vest already did a lot of work to make the existing Asciidoclet work and this are just some minor improvements; e.g:
-
Upgraded AsciiDocterJ version to 2.3.0
-
Added AsciiDoctor diagram to enable diagrams in javadoc comments.
Example
A Java class with Asciidoclet Javadoc
/**
* = Asciidoclet
*
* Sample plantuml diagram
* [plantuml,test]
* ----
* class BlockProcessor
* class DiagramBlock
* class DitaaBlock
* class PlantUmlBlock
*
* BlockProcessor <|-- DiagramBlock
* DiagramBlock <|-- DitaaBlock
* DiagramBlock <|-- PlantUmlBlock
* ----
*
* Sample comments that include `source code`.
*
* [source,java]
* --
* public class Asciidoclet extends Doclet {
* private final Asciidoctor asciidoctor = Asciidoctor.Factory.create();
*
* @SuppressWarnings("UnusedDeclaration")
* public static boolean start(RootDoc rootDoc) {
* new Asciidoclet().render(rootDoc);
* return Standard.start(rootDoc);
* }
* }
* --
*
* @author https://github.com/johncarl81[John Ericksen]
*/
public class Asciidoclet extends Doclet {
}
The result is readable source and beautifully rendered Javadocs, the best of both worlds!
Usage Maven
Asciidoclet may be used via a maven-javadoc-plugin doclet:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.2.0</version>
<configuration>
<additionalJOptions>
<additionalJOption>-J--add-exports=jdk.javadoc/jdk.javadoc.internal.tool=ALL-UNNAMED</additionalJOption> <!--(1)-->
<additionalJOption>-Xdoclint:all,-html,-accessibility,-missing</additionalJOption> <!--(2)-->
<additionalJOption>--base-dir</additionalJOption>
<additionalJOption>${project.basedir}</additionalJOption>
</additionalJOptions>
<doclet>org.asciidoctor.asciidoclet.Asciidoclet</doclet>
<docletArtifact>
<groupId>org.uniknow</groupId>
<artifactId>asciidoclet</artifactId>
<version>2.2.1</version>
</docletArtifact>
<detectJavaApiLink>true</detectJavaApiLink>
</configuration>
</plugin>
-
For the asciidoclet to work, it needs access to the internals of the
javadoctool. This incantation makes that access possible on moduler JDKs. -
Asciidoctor may generate HTML that produces doclint errors, which can cause the build to fail. To work around that, we have to disable these doclint categories.
Doclet Options
- --base-dir <dir>
-
Sets the base directory that will be used to resolve relative path names in Asciidoc
include::directives. This should be set to the project’s root directory. - -a, --attribute "name[=value], …"
-
Sets document attributes that will be expanded in Javadoc comments. The argument is a string containing a single attribute, or multiple attributes separated by commas.
This option may be used more than once, for example:
-a name=foo -a version=1.Attributes use the same syntax as Asciidoctor command-line attributes:
-
namesets the attribute (with an empty value) -
name=valueassignsvalueto the attribute. Occurrences of{name}in the Javadoc will be replaced by this value. -
name=value@assignsvalueto the attribute, unless the attribute is defined in the attributes file or Javadoc. -
name!unsets the attribute.
The document attribute
javadocis set automatically by the doclet. This can be used for conditionally selecting content when using the same Asciidoc file for Javadoc and other documentation. -
- -overview <file>
-
Overview documentation can be generated from an Asciidoc file using the standard
-overviewoption. Files matching*.adoc,*.ad,*.asciidocor*.txtare processed by Asciidoclet. Other files are assumed to be HTML and will be processed by the standard doclet.
