Asciidoclet 1.5.0 released!
by and -
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
| Group Id | Artifact Id | Version | Download |
|---|---|---|---|
org.asciidoctor |
| Group Id | Artifact Id | Version | Download |
|---|---|---|---|
org.asciidoctor |
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’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:
|
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:
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:
-
Install the Asciidoctor Diagram gem,
asciidoctor-diagram:$ gem install asciidoctor-diagram
-
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_PATHenvironment variable internally).2 The data-uriattribute is required so that the image data is embedded inside the generated HTML files.[1] -
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.
