Asciidoclet

Usage

Run Javadoc with the org.asciidoctor.asciidoclet.Asciidoclet doclet class as shown in the examples below. See Doclet Options below for supported options.

Note	Asciidoclet must use some Java runtime internals. That requires the use of `exports` and `open` configurations depending on the Java version in use.

Maven

Asciidoclet may be used via a maven-javadoc-plugin for the supported Java versions. Pay special attention to <additionalJOptions> to configure access to Java internals.

Java 11 example

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.6.3</version>
    <configuration>
        <source>11</source>
        <doclet>org.asciidoctor.asciidoclet.Asciidoclet</doclet>
        <docletArtifact>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoclet</artifactId>
            <version>{asciidoclet-version}</version>
        </docletArtifact>
        <overview>src/main/java/overview.adoc</overview>
        <additionalparam>
          --base-dir ${project.basedir}
          --attribute "name=${project.name}"
          --attribute "version=${project.version}"
          --attribute "title-link=https://example.com[${project.name} ${project.version}]"
        </additionalparam>
        <additionalJOptions>
            <additionalJOption>-J--add-exports=jdk.javadoc/jdk.javadoc.internal.tool=ALL-UNNAMED</additionalJOption>
            <additionalJOption>-Xdoclint:all,-html,-accessibility</additionalJOption>
        </additionalJOptions>
    </configuration>
</plugin>

Java 17+ example

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.6.3</version>
    <configuration>
        <source>17</source>
        <doclet>org.asciidoctor.asciidoclet.Asciidoclet</doclet>
        <docletArtifact>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoclet</artifactId>
            <version>{asciidoclet-version}</version>
        </docletArtifact>
        <overview>src/main/java/overview.adoc</overview>
        <additionalparam>
          --base-dir ${project.basedir}
          --attribute "name=${project.name}"
          --attribute "version=${project.version}"
          --attribute "title-link=https://example.com[${project.name} ${project.version}]"
        </additionalparam>
        <additionalJOptions>
            <additionalJOption>-J--add-exports=jdk.javadoc/jdk.javadoc.internal.tool=ALL-UNNAMED</additionalJOption>
            <additionalJOption>-J--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED</additionalJOption>
            <additionalJOption>-J--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED</additionalJOption>
            <additionalJOption>-J--add-exports=jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED</additionalJOption>
            <additionalJOption>-J--add-opens=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED</additionalJOption>
            <additionalJOption>-J--add-opens=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED</additionalJOption>
            <additionalJOption>-Xdoclint:all,-html,-accessibility</additionalJOption>
        </additionalJOptions>
    </configuration>
</plugin>

Gradle

Asciidoclet may be used via a doclet in the Javadoc task: Pay special attention to jFlags to configure access to Java internals.

Java 11 example

plugins {
    id 'java'
}

configurations {
    asciidoclet
}

dependencies {
    asciidoclet 'org.asciidoctor:asciidoclet:{asciidoclet-version}'
}

javadoc {
    options {
        docletpath = configurations.asciidoclet.files.asType(List)
        doclet = 'org.asciidoctor.asciidoclet.Asciidoclet'
        overview = "src/main/java/overview.adoc"
        addStringOption "-base-dir", "${projectDir}" // (1)
        addStringOption \
            "-attribute", // (2)
                "name=${project.name}," +
                "version=${project.version}," +
                "title-link=https://example.com[${project.name} ${project.version}]"
        jFlags \
            "--add-exports=jdk.javadoc/jdk.javadoc.internal.tool=ALL-UNNAMED"
    }
}

Option names passed to Gradle’s javadoc task must omit the leading "-", so here "-base-dir" means "--base-dir". See Doclet Options below.
Gradle’s javadoc task does not allow multiple occurrences of the same option. Multiple attributes can be specified in a single string, separated by commas.

Java 17+ example

plugins {
    id 'java'
}

configurations {
    asciidoclet
}

dependencies {
    asciidoclet 'org.asciidoctor:asciidoclet:{asciidoclet-version}'
}

javadoc {
    options {
        docletpath = configurations.asciidoclet.files.asType(List)
        doclet = 'org.asciidoctor.asciidoclet.Asciidoclet'
        overview = "src/main/java/overview.adoc"
        addStringOption "-base-dir", "${projectDir}" // (1)
        addStringOption \
            "-attribute", // (2)
                "name=${project.name}," +
                "version=${project.version}," +
                "title-link=https://example.com[${project.name} ${project.version}]"
        jFlags \
            "--add-exports=jdk.javadoc/jdk.javadoc.internal.tool=ALL-UNNAMED",
            "--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED",
            "--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED",
            "--add-exports=jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED",
            "--add-opens=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED",
            "--add-opens=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED"
    }
}

Option names passed to Gradle’s javadoc task must omit the leading "-", so here "-base-dir" means "--base-dir". See Doclet Options below.
Gradle’s javadoc task does not allow multiple occurrences of the same option. Multiple attributes can be specified in a single string, separated by commas.

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:

name sets the attribute (with an empty value)
name=value assigns value to the attribute. Occurrences of {name} in the Javadoc will be replaced by this value.
name=value@ assigns value to the attribute, unless the attribute is defined in the attributes file or Javadoc.
name! unsets the attribute.

The document attribute javadoc is set automatically by the doclet. This can be used for conditionally selecting content when using the same AsciiDoc file for Javadoc and other documentation.

--attributes-file <file>

Reads document attributes from an AsciiDoc file. The attributes will be expanded in Javadoc comments.

If <file> is a relative path name, it is assumed to be relative to the --base-dir directory.

Attributes set by the -a/--attribute option take precedence over those in the attributes file.

-r, --require <library>,…

Make the specified RubyGems library available to Asciidoctor’s JRuby runtime, for example -r asciidoctor-diagram.

This option may be specified more than once. Alternatively multiple library names may be specified in a single argument, separated by commas.

--gem-path <path>

Sets the GEM_PATH for Asciidoctor’s JRuby runtime. This option is only needed when using the --require option to load additional gems on the GEM_PATH.

-overview <file>

Overview documentation can be generated from an AsciiDoc file using the standard -overview option. Files matching *.adoc, *.ad, *.asciidoc or *.txt are processed by Asciidoclet. Other files are assumed to be HTML and will be processed by the standard doclet.

--asciidoclet-include <filter>

--asciidoclet-exclude <filter>

Explicitly include or exclude classes from being processed as AsciiDoc comments by ant-style path matching (see ant-style-path-matcher).

If --asciidoclet-include is specified, only classes and packages matching the include filter are processed. Likewise, if --include is unspecified, all classes are processed. If --asciidoclet-exclude is specified, classes matching the filter are not processed.

Both --asciidoclet-include and --asciidoclet-exclude can be mixed. In addition, classes excluded with --asciidoclet-exclude or not matching a specified --asciidoclet-include may be included by annotating the class level javadoc with @asciidoclet. Doing so allows writing one class at a time while respecting refactors. This feature allows the migration of documentation from HTML to AsciiDoc in a piecemeal way.

Modules
Module	Description
asciidoclet	A module-info for `asciidoclet`.

AsciiDoc Javadoc Doclet 2.0.0 API

Asciidoclet

Usage

Maven

Java 11 example

Java 17+ example

Gradle

Java 11 example

Java 17+ example

Doclet Options