Usage

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

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>2.0.0</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>2.0.0</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:2.0.0'
}

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"
    }
}
1 Option names passed to Gradle’s javadoc task must omit the leading "-", so here "-base-dir" means "--base-dir". See Doclet Options.
2 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:2.0.0'
}

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"
    }
}
1 Option names passed to Gradle’s javadoc task must omit the leading "-", so here "-base-dir" means "--base-dir". See Doclet Options.
2 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.