ExportDoclet

A Doclet that allows exporting javadoc comments containing AsciiDoc text to AsciiDoc files, enabling combining the javadocs into a broader AsciiDoc documentation for your Java project.

Instead of exporting the javadoc comments to standard HTML files, the ExportDoclet exports them to AsciiDoc files, that in turn can be converted to any output format supported by the AsciiDoctor toolchain.

Using the ExportDoclet, one can put together the source code documentation (javadocs written in AsciiDoc), quick start guides, user guides, FAQs and any other documentation for Java projects.

AsciiDoc is a non-disturbing and clean markup language that you can use to write your javadocs. It provides a fast, elegant and professional way to write your documentation, beyond allowing the use of several new resources such as automatic code highlight and inclusion of snippets of code from your source files, providing a powerful way to keep your documentation updated with your code.

ExportDoclet encourages developers to write meaninguful and expanded documentation that goes beyond the source code documentation, by enabling the integration with other plugins such as the AsciiDoclet and Maven AsciiDoctor Plugin.

Building the ExportDoclet

ExportDoclet is a Java Maven project that can be built directly from any IDE or using the following maven command:

mvn clean install

That will build the tool and install it at your local maven repository, usually at the .m2 directory inside your home directory.

How to use ExportDoclet

There are different ways to use the ExportDoclet together with the javadoc tool, depending on your goal and project type. The next sub-sections present some of these ways.

Using the ExportDoclet with javadoc by command line

To manually call the javadoc tool by command line using the ExportDoclet you have to follow the next steps in a terminal:

• Enter into the folder that contains the java files with javadoc comments you want to export

• Execute javadoc -docletpath $DOCLETJAR -doclet org.asciidoctor.ExportDoclet -d $OUTPUTDIR *.java, where:

  • $DOCLETJAR is the path for the ExportDoclet jar file (that you built using the instructions in the previous section, or downloaded from maven central or bintray)

  • $OUTPUTDIR is where you want to save the exported asciidoc files.

Using ExportDoclet with Maven javadoc plugin

Using the ExportDoclet with Maven is pretty simple. You can include the maven-javadoc-plugin configuration inside the <build> section of project’s pom.xml file, defining the required configuration for the javadoc command line tool that was used above.

The sub-sections below present some distinct configurations.

Generating only the AsciiDoc files

To generate just the AsciiDoc files and ignore the genration of the default HTML files, you can include the following code to the <build> section of your project’s pom.xml.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.4</version>
    <configuration>
        <doclet>org.asciidoctor.ExportDoclet</doclet>
        <docletArtifact>
            <groupId>org.asciidoctor</groupId>
            <artifactId>exportdoclet</artifactId>
            <version>1.5.4-SNAPSHOT</version>
        </docletArtifact>
        <useStandardDocletOptions>true</useStandardDocletOptions>
    </configuration>
</plugin>

Now, to generate the javadocs in AsciiDoc files you can execute the javadoc:javadoc goal in Maven, using your IDE or the command line inside your project root directory:

mvn javadoc:javadoc

The exported javadocs to AsciiDoc files will be found at target/site/apidocs directory.

Generating both the AsciiDoc and default HTML files

If you want to generate both the AsciiDoc and HTML files, that requires two different configurations for the maven-javadoc-plugin, as exemplified below. That includes the AsciiDoclet to enable converting the AsciiDoclet tags inside your javadoc comments to HTML tags.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.4</version>
    <executions>
        <!-- Exports javadocs containing AsciiDoc to HTML -->
        <execution>
            <id>html</id>
            <phase>package</phase>
            <goals>
                <goal>javadoc</goal>
            </goals>
            <configuration>
                <doclet>org.asciidoctor.Asciidoclet</doclet>
                <docletArtifact>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoclet</artifactId>
                    <version>1.5.4</version>
                </docletArtifact>
                <additionalparam>
                    --base-dir ${project.basedir}
                    --attribute "name=${project.name}"
                    --attribute "version=${project.version}"
                </additionalparam>
            </configuration>
        </execution>
        <!-- Exports javadocs containing AsciiDoc to AsciiDoc files -->
        <execution>
            <id>asciidoc</id>
            <phase>package</phase>
            <goals>
                <goal>javadoc</goal>
            </goals>
            <configuration>
                <doclet>org.asciidoctor.ExportDoclet</doclet>
                <docletArtifact>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>exportdoclet</artifactId>
                    <version>1.5.4-SNAPSHOT</version>
                </docletArtifact>
                <useStandardDocletOptions>true</useStandardDocletOptions>
                <additionalparam>
                    -d "${project.build.directory}/site/asciidocs"
                </additionalparam>
            </configuration>
        </execution>
    </executions>
</plugin>

Now, to generate the javadocs both in AsciiDoc and HTML files, you can execute the package goal in Maven, using your IDE or the command line inside your project root directory:

mvn clean package

You can see a sample project that has some java files with javadocs containing AsciiDoc, and that has everything configured in the pom.xml.

How to use the generated AsciiDoc Files

After using the ExportDoclet to export the javadoc comments written in AsciiDoc, you can put together your entire project documentation (javadocs, quick start guides, user guides, FAQs, etc) and exporting them to several different formats such as beautiful HTMLs, PDF, epub or any other format supported by AsciiDoctor.

In order to accomplish that, you can use the Maven AsciiDoctor Plugin to automate the process of collecting all AsciiDoc files, that compound the entire project documentation, and export them to any deployment format such as HTML or PDF.

Contributors

• Manoel Campos da Silva Filho

Additional References

• The javadoc Command Line Manual

• The javadoc Tool Home Page

• Maven javadoc Plugin

• AsciiDoclet

• Maven AsciiDoctor Plugin