Asciidoclet

The Asciidoclet project allows developers to write their code Javadoc API documentation using AsciiDoc. This plugin renders the AsciiDoc contents when previewing the documentation.

Support for this is available from AsciiDoc Plugin release 0.30.83 for IntelliJ IDEA 2019.3+ and 0.31.9 for IntelliJ IDEA 2020.2+.

Starting with AsciiDoc Plugin release 0.31.13 it moved to a separate Asciidoclet Plugin as it prevented the AsciiDoc Plugin to be dynamically installable without a restart.

This feature is in its early development and marked “experimental”. Its functionality might change over time.

How to use it

Using IntelliJ 2020.2+

Users need to install the Asciidoclet plugin:

Steps
  1. Open the IDE’s setting via File  Settings…​

  2. Select Plugins from the settings tree

  3. Select Marketplace tab if it is not selected yet

  4. Search for 'asciidoclet'

  5. Click on Install.
    As the Asciidoclet plugin depends on the AsciiDoc plugin, the IDE will ask to install the AsciiDoc plugin as well if it is not already installed.

  6. Once the download is complete, restart the IDE

After the restart the Quick-Help (Ctrl+Q) will render all Javadoc-comments as AsciiDoc. This is a global setting for all projects. To change the settings, follow these steps:

Steps
  1. Open the menu File  Settings…​  Languages & Frameworks  Asciidoclet

  2. Check or un-check the checkbox “Enable Asciidoclet support (AsciiDoc in Javadoc)”

Since IDEA release 2020.1 users can choose to show Javadoc comments rendered in the editor. With IDEA release 2020.2 and the latest version of the Asciidoclet Plugin this is supported for Asciidoclet as well. See chapter “Render Javadocs” in the IDEA documentation for more information.

Using IntelliJ 2019.3+

Users need to enable this feature in the plugin’s settings:

Steps
  1. Open the menu File  Settings…​  Languages & Frameworks  AsciiDoc

  2. Check the checkbox “Enable Asciidoclet support (AsciiDoc in Javadoc)”

Once this check-box is enabled, the Quick-Help (Ctrl+Q) will render all Javadoc-comments as AsciiDoc. This is a global setting for all projects.

Since IDEA release 2020.1 users can choose to show Javadoc comments rendered in the editor. This is supported with the Asciidoclet plugin from IntelliJ 2020.2 onward only.

Detection of Asciidoclet vs. Javadoc

When working in different projects there might AsciiDoc used in some files, but not in others. Libraries might use JavaDoc, some not.

As default the plugin will render all Javadoc contents as AsciiDoc with the following exception:

  1. If the Javadoc contents contain a HTML tag <p> the plugin assumes the contents should be rendered as standard Javadoc without the AsciiDoc conversion.

Preview while editing Asciidoclet

When editing Javadoc content users can open a quick docs in a separate window that stays open permanently. It will always show the documentation related to the current cursor’s position.

When editing the Javadoc contents, the documentation window will show the update Asciidoc rendered version with a short delay.

To show the documentation window choose the menu item View  Tool Windows  Documentation (sometimes hidden based on the current context at the cursor position) or by pressing Ctrl+Q twice.

Limitations

Annotations in Javadoc code snippets

While Asciidoclet supports annotations within Javadoc code snippets, this plugin doesn’t as it breaks parsing of the content.

Instead of writing content like this:

/**
 * [source,java]
 * --
 *     @SuppressWarnings("UnusedDeclaration")
 *     /*...*/
 * --
...

Please rewrite it like this:

/**
 * [source,java]
 * --
 *     {at}SuppressWarnings("UnusedDeclaration")
 *     /*...*/
 * --
...

Start path of includes

Includes will use path relative to the root of the project. While Asciidoclet allows users to override the path on the command line, the plugin doesn’t allow for in the current version.

HTML styling of Asciidoclet

When viewing rendered Asciidoclet content in the documentation window IDEA supports only a limited amount of CSS styling. One example are section headlines: they all have the same size and font as regular text.

Syntax Highlighting when writing Asciidoclet

The current version of the plugin doesn’t provide AsciiDoc language injection for the Javadoc content. Therefore writers miss autocompletion in the editor. Please vote for this in issue IDEA-231876 at JetBrains to raise attention for this or contribute to the IntelliJ community edition.