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.

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 the Install button.
    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 uncheck the checkbox “Enable Asciidoclet support (AsciiDoc in Javadoc)”

Since IDEA release 2020.1 users can choose to show Javadoc comments rendered by 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.

Detection of Asciidoclet vs. Javadoc

When working in different projects, there might be 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 an 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 quick docs in a separate window that stays open permanently. It will always show the documentation related to the current at the 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.

Reformatting Settings

The default setup of IntelliJ will add the HTML tag <p> on blank lines in Asciidoclet content. This will break the AsciiDoc syntax.

This is due to IntelliJ treating Asciidoclet as JavaDoc when reformatting.

A minimal recommended setting is to disable adding <p> to empty lines.

To disable this, use either IDE’s settings, or use an EditorConfig file. The instructions below describe both approaches.

Configure Reformatting of AsciiDoclet via IDE Settings

The user can change the settings via File  Settings…​  Editor  Code Style  Java  JavaDoc  Other and uncheck the option ‘Generate "<p>" on empty lines’.

The changes are effective once the user confirms the settings via Apply or OK.

javadoc formatting settings
Figure 1. IntelliJ’s AsciiDoc formatting settings

Configure Reformatting of AsciiDoclet via EditorConfig

IntelliJ supports the EditorConfig standard to configure re-formatting options on a per-project and per-folder level. Read and find out more about it in the IntelliJ blog.

All IntelliJ reformatting options are available in EditorConfig files and are prefixed with ij_. Autocompletion shows all available options. The .editorconfig file affects all project files in its folder and its sub-folders. A file with root = true is usually located in the root folder of the project and indicates the main configuration file. Additional .editorconfig files in a sub-folder can override settings in the file tree they are located in.

After creating the file, re-opening the project might be necessary for the IntelliJ settings to take effect.

Find an example below.

.editorconfig example with AsciiDoclet settings
# .editorconfig
# see https://editorconfig.org/ for the documentation
root = true

[*.java]
ij_java_doc_add_p_tag_on_empty_lines = false

# optional: also preserve all line breaks
# ij_java_doc_preserve_line_breaks = true
# optional: disable all JavaDoc formatting
# ij_java_doc_enable_formatting = false

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")
 *     /\*...*/
 * --
...

Rewrite it like this:

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

Start path of includes

Includes will use a 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 the 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. Vote for this in issue IDEA-231876 at JetBrains to raise attention to this or contribute to the IntelliJ community edition.