Documentation

Custom languages can display documentation for various constructs, such as functions, methods, classes, or others, directly within the IDE. To access the documentation, users can either select View | Quick Documentation or hover over a symbol. This will open a popup that displays type information, parameters, usage descriptions, or examples. The source of the documentation content can vary. While it is often extracted from comments in the source code (e.g., Javadoc comments), external resources, such as web pages, can also be accessed.

From IntelliJ Platform version 2023.1 onwards, plugin developers can choose to implement one of three extension points (EPs) from the new Documentation Target API based on the specific use-case. These EPs enable building documentation from offsets in the current editor, PSI elements, or Symbols. Detailed information on implementing these EPs can be found in the Documentation Target API section.

Documentation Target API

Custom language developers have the flexibility to select from three distinct EPs for providing documentation to their users. To ensure clarity and avoid confusion, we provide a high-level summary of the overall approach, outlining the primary components and their interactions.

Overall Approach

Implement one of the EPs below which should extract the necessary entity (e.g. a PSI element) for which the documentation is requested. It returns instances of DocumentationTarget, which will be explained in a later section.
The implementation of DocumentationTarget provides the functionality to compute the rendered documentation, its presentation in the documentation tool window, or separate hints that are displayed when hovering over code.
The rendered documentation is an instance of DocumentationResult, which wraps the documentation in HTML format but can also include images or external URLs. DocumentationResult can be used asynchronously when building the documentation would take too long and block the IDE.

DocumentationTargetProvider: Implement DocumentationTargetProvider and register it as com.intellij.platform.backend.documentation.targetProvider extension point to build documentation for a certain offset in a PsiFile by overriding documentationTargets().
PsiDocumentationTargetProvider: Implement PsiDocumentationTargetProvider and register it as com.intellij.platform.backend.documentation.psiTargetProvider extension point to build documentation for PSI elements by overriding documentationTarget().
SymbolDocumentationTargetProvider: Implement SymbolDocumentationTargetProvider and register it as com.intellij.platform.backend.documentation.symbolTargetProvider extension point to build documentation for Symbols by overriding documentationTarget().

`DocumentationTarget`

Each of the implementations above returns instances of DocumentationTarget. The main work is done in computeDocumentation() where the documentation is built from the available information. If a plugin implemented the now deprecated DocumentationProvider before, then computeDocumentation() should do the work that was formerly done in DocumentationProvider.generateDoc().

In addition to showing the documentation, the computeDocumentationHint() method returns the text to be displayed when the user hovers over an element with Ctrl/Cmd pressed or when Settings | Editor | Code Editing | Show quick documentation on hover is enabled. In the old framework, this method was called DocumentationProvider.getQuickNavigateInfo().

The createPointer() method manages instance restoration and ensures access to the entity across different read actions. When implementing the createPointer() method, it is essential to handle invalidated PSI elements. Unlike PSI elements, the DocumentationTarget API does not include an isValid() method and the returned pointer is expected to be null if the instance (and all contained objects) cannot be restored. See KotlinDocumentationTarget.createPointer() as a reference.

Examples

Documentation Provider API

Custom language developers usually extend from AbstractDocumentationProvider instead of implementing the DocumentationProvider interface. This implementation needs to be registered in com.intellij.lang.documentationProvider extension point.

The main work is done in generateDoc(), which has two PSI element arguments: the target element for which the documentation is requested and the original element under the cursor. If IntelliJ Platform's choice of the target element isn't suitable for your language, you can override getCustomDocumentationElement() and provide the correct element.

Once these steps are completed, the following additional features can be implemented:

Implement getQuickNavigateInfo() to provide the text that should be displayed when an element is hovered over with Ctrl/Cmd pressed.
Implement generateHoverDoc() to show different contents on mouse hover.
Implement getDocumentationElementForLookupItem() to return a suitable PSI element for the given lookup element when View | Quick Documentation is called on an element of the autocompletion popup.
Implement getUrlFor() and ExternalDocumentationProvider to fetch documentation for elements from online resources.

Examples

The custom language tutorial contains a step-by-step guide for the DocumentationProvider of the Simple language. In addition, several implementations of other languages exist in the IntelliJ Platform code, for instance:

The Properties Language plugin has a small and easy-to-understand DocumentationProvider similar to the one shown in the custom language tutorial.
Usage examples for DocumentationMarkup can be found in ThemeJsonDocumentationProvider.

Further tips

Additionally, custom actions can be incorporated into documentation inlays and popups using the DocumentationActionProvider. This provider should be registered with the com.intellij.documentationActionProvider extension point.

How the documentation for the target element is created is up to the custom language developer. A common choice is to extract and format documentation comments. To format the documentation contents, you should use DocumentationMarkup to achieve a consistent output.

Last modified: 13 June 2024