Skip to content

This is a guide for setting up and using the Asciidoclet within a JDK 11 project. Asciidoclet is a Javadoc Doclet based on Asciidoctor that lets you write Javadoc in the AsciiDoc syntax.

License

Notifications You must be signed in to change notification settings

UniKnow/AsciiDoclet

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

14 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Asciidoclet & Diagram for JDK 11

Build Status Javadoc

Asciidoclet is a Javadoc Doclet based on Asciidoctor that lets you write Javadoc in the AsciiDoc syntax.

However, Java 9 completely changed the internal JavaDoc APIs in incompatible ways, making the existing Asciidoclet unusable from Java 9 onward. Chris Vest already did a lot of work to make the existing Asciidoclet work and this are just some minor improvements; e.g:

  • Upgraded AsciiDocterJ version to 2.3.0

  • Added AsciiDoctor diagram to enable diagrams in javadoc comments.

Example

A Java class with Asciidoclet Javadoc

/**
* = Asciidoclet
*
* Sample plantuml diagram
* [plantuml,test]
* ----
* class BlockProcessor
* class DiagramBlock
* class DitaaBlock
* class PlantUmlBlock
*
* BlockProcessor <|-- DiagramBlock
* DiagramBlock <|-- DitaaBlock
* DiagramBlock <|-- PlantUmlBlock
* ----
*
* Sample comments that include `source code`.
*
* [source,java]
* --
* public class Asciidoclet extends Doclet {
*     private final Asciidoctor asciidoctor = Asciidoctor.Factory.create();
*
*     @SuppressWarnings("UnusedDeclaration")
*     public static boolean start(RootDoc rootDoc) {
*         new Asciidoclet().render(rootDoc);
*         return Standard.start(rootDoc);
*     }
* }
* --
*
* @author https://github.com/johncarl81[John Ericksen]
*/
public class Asciidoclet extends Doclet {
}

The result is readable source and beautifully rendered Javadocs, the best of both worlds!

Usage Maven

Asciidoclet may be used via a maven-javadoc-plugin doclet:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.2.0</version>
    <configuration>
         <additionalJOptions>
             <additionalJOption>-J--add-exports=jdk.javadoc/jdk.javadoc.internal.tool=ALL-UNNAMED</additionalJOption> <!--(1)-->
             <additionalJOption>-Xdoclint:all,-html,-accessibility,-missing</additionalJOption> <!--(2)-->
             <additionalJOption>--base-dir</additionalJOption>
             <additionalJOption>${project.basedir}</additionalJOption>
         </additionalJOptions>
         <doclet>org.asciidoctor.asciidoclet.Asciidoclet</doclet>
         <docletArtifact>
             <groupId>org.uniknow</groupId>
             <artifactId>asciidoclet</artifactId>
             <version>2.2.1</version>
         </docletArtifact>
         <detectJavaApiLink>true</detectJavaApiLink>
    </configuration>
</plugin>
  1. For the asciidoclet to work, it needs access to the internals of the javadoc tool. This incantation makes that access possible on moduler JDKs.

  2. Asciidoctor may generate HTML that produces doclint errors, which can cause the build to fail. To work around that, we have to disable these doclint categories.

Doclet Options

--base-dir <dir>

Sets the base directory that will be used to resolve relative path names in Asciidoc include:: directives. This should be set to the project’s root directory.

-a, --attribute "name[=value], …​"

Sets document attributes that will be expanded in Javadoc comments. The argument is a string containing a single attribute, or multiple attributes separated by commas.

This option may be used more than once, for example: -a name=foo -a version=1.

Attributes use the same syntax as Asciidoctor command-line attributes:

  • name sets the attribute (with an empty value)

  • name=value assigns value to the attribute. Occurrences of {name} in the Javadoc will be replaced by this value.

  • name=value@ assigns value to the attribute, unless the attribute is defined in the attributes file or Javadoc.

  • name! unsets the attribute.

The document attribute javadoc is set automatically by the doclet. This can be used for conditionally selecting content when using the same Asciidoc file for Javadoc and other documentation.

-overview <file>

Overview documentation can be generated from an Asciidoc file using the standard -overview option. Files matching *.adoc, *.ad, *.asciidoc or *.txt are processed by Asciidoclet. Other files are assumed to be HTML and will be processed by the standard doclet.

About

This is a guide for setting up and using the Asciidoclet within a JDK 11 project. Asciidoclet is a Javadoc Doclet based on Asciidoctor that lets you write Javadoc in the AsciiDoc syntax.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published