Write Javadocs in AsciiDoc with Asciidoclet
by -
We’re excited to announce the newest member of the Asciidoctor family, Asciidoclet. Asciidoclet is a Javadoc Doclet based on Asciidoctor that enables developers to write Javadoc comments using the AsciiDoc syntax.
Motivation
From the very beginning, a concept the designers of Java got right was to include documentation with source code. This allowed documentation to stay closer in sync with ever-changing source and allowed multiple viewing platforms, most notably the HTML generation and IDE integration.
The main drawback of Javadoc has been the requirement to use embedded HTML fragments to achieve advanced (or even modest) formatting. This is where the AsciiDoc integration shines. Being a lightweight markup language, AsciiDoc gives developers access to advanced formatting without having to fiddle with low-level HTML markup. In other words, developers can focus on the content rather than the markup and still achieve a beautiful end result.
Pairing AsciiDoc with Javadocs means readable source and beautifully rendered Javadocs, the best of both worlds!
Usage
Once Asciidoclet is plugged into Javadoc, it’s just a matter of using AsciiDoc mark up in Javadocs. The following example demonstrates a number of features of Asciidoclet:
/**
* = Asciidoclet (1)
*
* Sample comments that include +source code+. (2)
*
* [source,java] (3)
* --
* public class Asciidoclet extends Doclet {
* private final Asciidoctor asciidoctor = Asciidoctor.Factory.create();
*
* @SuppressWarnings("UnusedDeclaration") (4)
* public static boolean start(RootDoc rootDoc) {
* new Asciidoclet().render(rootDoc);
* return Standard.start(rootDoc);
* }
* }
* --
*
* @author https://github.com/johncarl81[John Ericksen] (5)
*/
public class Asciidoclet extends Doclet {
}| 1 | Titles are easy to create using the = markup. |
| 2 | Paragraphs are the default and do not require the <p> html tag. Inline source may be marked up by surrounding the text in + symbols. |
| 3 | Source is easily marked up using the [source,language] tag and block delimiters, --, also called "fences" |
| 4 | The notorious @ symbol is automatically handled by Asciidoclet, avoiding the standard {@literal @} boilerplate. |
| 5 | Inline AsciiDoc markup is available within Javadoc tags. This example highlights link rendering. |
Distribution
Asciidoclet is published to Maven Central. The artifact information is summarized in the table below.
| Group Id | Artifact Id | Version | Download |
|---|---|---|---|
org.asciidoctor |
* This release is based on the Asciidoctor 0.1.3 release.
Installation
Asciidoclet is a standard Javadoc Doclet and may be used as such. One of the easiest ways to install Asciidoclet is by adding it as a Doclet to the maven-javadoc-plugin:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
<configuration>
<doclet>org.asciidoctor.Asciidoclet</doclet>
<docletArtifact>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoclet</artifactId>
<version>${asciidoclet.version}</version>
</docletArtifact>
</configuration>
</plugin>We hope that this extension helps you push your Javadocs to new heights. As always, collaboration is welcome and you may find (and fork) the source on GitHub.
A big thanks to Alex Soto of the Asciidoctor Java integration project, Jason Porter and Dan Allen for their feedback and support and everyone else who contributes to the Asciidoctor project. Writing this extension could not have been easier because of the great work and collaboration of the Asciidoctor community.