Asciidoclet 1.5.0 released!

by John Ericksen and Ben Evans -

Following on from the releases of Asciidoctor 1.5.0 and AsciidoctorJ 1.5.0, version 1.5.0 of Asciidoclet has been released with several significant new features, including a new look & feel!

What is Asciidoclet?

Asciidoclet allows Java developers to write Javadoc comments in the portable and rich AsciiDoc syntax instead of HTML.

In short, why write messy Javadoc like this?

/**
 * This class has the following features:
 * <ul>
 *   <li>Support for <strong>foo</strong></li>
 *   <li>Support for bar</li>
 * </ul>
 */
public class Thing implements Something { ... }

…​when you can write tidy Javadoc like this!

/**
 * This class has the following features:
 *
 * - Support for *foo*
 * - Support for bar
 */
public class Thing implements Something { ... }

Much better! Now comments in the source code are much easier to read and write and can be reused outside of Javadoc. Best of all, the HTML generated from Javadoc still looks great (perhaps even better).

Of course, this example just scratches the surface of what’s possible. Tables, lists, code examples with syntax highlighting, links, includes and all of Asciidoctor’s capabilities are available via the lightweight AsciiDoc syntax.

Now, developers can focus on content rather than formatting, and still achieve a beautiful end result.

Artifact information

Artifact information (jCenter @ Bintray)
Group Id Artifact Id Version Download

org.asciidoctor

asciidoclet

1.5.0

pom jar javadoc (jar) sources (jar)

Artifact information (Maven Central)
Group Id Artifact Id Version Download

org.asciidoctor

asciidoclet

1.5.0

pom jar javadoc (jar) sources (jar)

Installing

In Maven, just add the Asciidoclet doclet name and artifact to the maven-javadoc-plugin declaration:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>2.9</version>
  <executions>
    <execution>
      <goals>
        <goal>jar</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <doclet>org.asciidoctor.Asciidoclet</doclet>
    <docletArtifact>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoclet</artifactId>
      <version>1.5.0</version>
    </docletArtifact>
  </configuration>
</plugin>

See the Asciidoclet guide for examples that apply to other build systems and all the available doclet options.

Release highlights

Built on Asciidoctor 1.5.0

Asciidoclet inherits all of the improvements from Asciidoctor 1.5.0 and AsciidoctorJ 1.5.0.

Asciidoctor 1.5.0 introduced some syntax changes. Please refer to the migration guide for details about how to migrate your content.

Improved stylesheets

Asciidoclet includes a default stylesheet with styles from Asciidoctor 1.5.0. This means that AsciiDoc content in the Javadoc is rendered with a similar look and feel to Asciidoctor in other environments.

Javadoc output
Figure 1. Example Javadoc using the Java 8-derived stylesheet

Javadoc’s HTML output varies between releases of the Java platform, so Asciidoclet selects an appropriate stylesheet based on the Java version it is running under:

  • For Java 7 & 8, a stylesheet based on the default Java 8 Javadoc stylesheet is used.

  • For Java 5 & 6, the stylesheet is based on the Java 6 Javadoc stylesheet.

If you want to use your own stylesheet, you can still do this by using Javadoc’s -stylesheetfile option.

AsciiDoc overview files

Javadoc’s -overview option lets you specify an HTML file that will be used as the overview or index page in the generated documentation. This is especially useful for larger projects, where the overview can provide users with a useful introduction and help them to navigate the API.

Asciidoclet now supports overview files written in AsciiDoc as well, with full support for AsciiDoc features such as includes and document attributes. Overview files named *.adoc, *.ad, *.asciidoc or *.txt are processed by Asciidoclet. Other files are assumed to be HTML, and will be processed by Javadoc’s standard doclet.

Document attributes

Asciidoclet now fully supports Asciidoctor’s document attributes. These are one of Asciidoctor’s most powerful features. Document attributes are parameters that can be passed to Asciidoctor to affect how the final output is generated.

Attributes are specified using one or more -a (or --attribute) options when running Asciidoclet. The --attributes-file option reads attributes from an AsciiDoc file. The attributes are passed to Asciidoctor when it renders Javadoc comments.

Here are some examples of how document attributes might be useful in your Javadoc.

Variable substitution

Attribute references in Javadoc comments or overview files are replaced with attribute values:

/**
 * {product-name} will change your life!
 * @version {version}
 */

When the doclet is run with -a product-name=Foo -a version=1.0, Asciidoctor replaces all {product-name} and {version} attribute references with the given values in the generated HTML output. This makes it very simple to inject values into the Javadoc, without changing the source.

Conditional inclusion

AsciiDoc’s conditional directives can selectively include content based on the presence or absence of attributes. This is useful when the same AsciiDoc source is used in different environments.

For example, if you wanted to reuse the same AsciiDoc content in your Javadoc overview page and your web site, but with some differences, you can use attributes to tell Asciidoctor when certain content should be included:

= Documentation for the Foo project

ifdef::javadoc[]
// content that should only appear in Javadoc
endif::javadoc[]

ifdef::my-website[]
// content that should only appear on the web site
endif::my-website[]

Asciidoclet automatically sets the javadoc attribute when it runs, so Javadoc-only content can easily be selected. You can of course define your own attributes as well.

Java and Ruby extension support

Asciidoctor can be extended using Java or Ruby libraries, and Asciidoclet inherits this capability as well.

  • Java extensions are loaded automatically when they are made available in the classpath, using AsciidoctorJ’s Extension SPI.

  • Ruby libraries (Gems) are loaded using the -r (or --require) option.

When using the --require option, we recommend specifying the --gem-path option as well to explicitly set the location of installed gems. Doing so ensures that your build remains portable and reproducible. You can use the gem-maven-plugin to install gems directly into your build directory.

Many extensions are available, but one that is probably most useful for Javadoc authors is Asciidoctor Diagram. Let’s see how it can be used with Asciidoclet.

Embedding diagrams in Javadoc

Asciidoctor Diagram is a popular Asciidoctor extension that lets you embed plain text diagram descriptions in your AsciiDoc source, which get rendered to images when Asciidoctor runs. This can be extremely valuable in Javadoc for describing the architecture or behavior implemeted by the software.

Here’s an example of a Javadoc comment containing a PlantUML sequence diagram:

/**
 * This class implements the following protocol:
 *
 * [plantuml]
 * ....
 * Alice -> Bob: Authentication Request
 * Bob --> Alice: Authentication Response
 *
 * Alice -> Bob: Another authentication Request
 * Alice <-- Bob: another authentication Response
 * ....
 */
public class AuthServer { ... }

Here’s how the diagram above appears in the Javadoc output:

Example output using Asciidoctor Diagram
Figure 2. Example output using Asciidoctor Diagram

Not bad! Developers can easily view and update diagrams in plain text, and users reading the Javadoc will see nicely rendered images.

Many other types of diagrams are supported, including Graphviz, blockdiag and ditaa. See the documentation for Asciidoctor Diagram for more examples.

To enable Asciidoctor Diagram support in Asciidoclet:

  1. Install the Asciidoctor Diagram gem, asciidoctor-diagram:

    $ gem install asciidoctor-diagram
  2. Run Asciidoclet with the following doclet options:

    --require asciidoctor-diagram
    --gem-path ${env.GEM_PATH} (1)
    --attribute data-uri (2)
    1 The --gem-path ${env.GEM_PATH} option tells Asciidoctor’s JRuby runtime where to find gems when using --require (effectively setting the $GEM_PATH environment variable internally).
    2 The data-uri attribute is required so that the image data is embedded inside the generated HTML files.[1]
  3. Admire the beautiful diagrams adorning your Javadoc!

Thanks!

We hope this new version makes your Javadocs even better. We appreciate everyone who has contributed to Asciidoclet. If you have ideas about how to improve on it, ideas and pull requests are always welcome via the repository on GitHub.


1. Without the data-uri attribute, Asciidoctor Diagram writes image files to a location that doesn’t line up with the generated HTML. This problem is being addressed in Asciidoctor Diagram at the time of writing. Refer to issue #39 for details.