Awesome Asciidoctor: Using Asciidoctor In Javadoc Comments

Asciidoctor is a great tool for writing technical documentation. The documentation to our Java source is what we write in Javadoc comments. Wouldn't it be nice if we could use Asciidoctor in our Javadoc comments? Of course! We can achieve this with the Asciidoclet Javadoc doclet. The doclet processes the Javadoc comments as Asciidoctor source and generates HTML in the final Javadoc documentation. We can use all of Asciidoc syntax like tables, lists, include directives, styling and more. We can even use Asciidoctor extensions like asciidoctor-diagram.

In the following Java source code we have Javadoc comments with Asciidoctor syntax. We have document attributes, list, styling, include macro, table and asciidoctor-diagram code in our Javadoc. Notice that we don't have the clutter of HTML tags we normally we would have if we write Javadoc.

package com.mrhaki.sample;

/**
 * = Application
 *
 * Project version: {projectVersion}.
 *
 * Sample Java application in project {projectName}
 * to show Asciidoclet as replacement for the
 * default Javadoclet.
 *
 * We can apply Asciidoc syntax in our Javadoclet
 * comments, like:
 *
 *  - `code`
 *  - **bold**
 *  - _italics_
 *
 * include::./src/main/javadoc/usage.adoc[]
 *
 * [plantuml]
 * ....
 * hide footbox
 *
 * actor Client
 * Client -> Application : main()
 * ....
 *
 * @author mrhaki
 * @version 1.0
 */
public class Application {

    /**
     * Main method to start the application.
     *
     * The following arguments are allowed
     * (easy Asciidoc table syntax):
     *
     * |===
     * | Name | Description
     *
     * | --help
     * | Getting more help about the application.
     *
     * | --info
     * | Show extra logging information
     *
     * |===
     *
     */
    public static void main(final String... arguments) {
        System.out.println("Application started...");
    }

}

Next we create a Gradle build file and configure the javadoc task to use the Asciidoclet Javadoc doclet. In our Java class we also used the asciidoctor-diagram support and therefore we also need to set up the Gradle jruby plugin.

plugins {
    // jruby plugin needed for asciidoctor-diagram gem.
    id 'com.github.jruby-gradle.base' version '0.1.5'
}
apply plugin: 'java'

version = '1.2.1'

ext {
    asciidoctorDocletVersion = '1.5.2'
}

configurations {
    // Extra configuration to assign Asciidoclet dependencies to.
    // This way the dependency will not interfer with oterh configurations.
    asciidoctorDoclet
}

repositories.jcenter()

dependencies {
    // Define dependencies for Asciidoclet.
    asciidoctorDoclet group: 'org.asciidoctor',
                 name: 'asciidoclet',
                 version: project.asciidoctorDocletVersion

    // Define dependency on asciidoctor-diagram Ruby gem.
    // Only needed when we want to use asciidoctor-diagram in our Javadoc.
    gems 'rubygems:asciidoctor-diagram:1.2.0'
}

// Download required gems. Only when we need gems in our Javadoc.
javadoc.dependsOn jrubyPrepareGems

javadoc {
    // Configure Javadoc options.
    options.with {
        // Configure Asciidoclet class path and class name
        // for the Javadoc task.
        docletpath = configurations.asciidoctorDoclet.files.asType(List)
        doclet = 'org.asciidoctor.Asciidoclet'

        // Set base dir. E.g. used for include directives.
        // Asciidoclet attributes need to be prefixed with -.
        // - is turned into -- when Javadoc tool is executed.
        addStringOption '-base-dir', projectDir.toString()

        // We can add Asciidoc document attributes and use them
        // in our Javadoc comments. E.g. {projectName}.
        def attributes = [projectName: project.name,
                          projectVersion: project.version]

        // Configure Asciidoclet to use asciidoctor-diagram gem.
        addStringOption '-require', 'asciidoctor-diagram'
        addStringOption '-gem-path', jrubyPrepareGems.outputDir.absolutePath
        // Include generated diagram inline.
        attributes['data-uri'] = ''

        // Combine document attributes with key/value pairs separated
        // by a comma. These are the document attributes passed
        // on to Asciidoctor.
        addStringOption '-attribute', attributes*.toString().join(',')

        // Overview document can also be a Asciidoctor document.
        overview = 'src/main/javadoc/overview.adoc'

        // Show version and author tags.
        // Normal Javadoc tags are correctly processed.
        version = true
        author = true
    }
}

When we run the javadoc task we get the generated output. For example part of the generated documentation for our Application class looks like this: