9.9 KiB
Documentation
Providing code documentation displayed in the popup invoked by hovering over a symbol or invoking the "View | Quick Documentation" action.
Product Help: Quick 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 section.
Plugins targeting versions earlier than 2023.1 must use the Documentation Provider API. Note that as long as the transition to the new API is not complete, the custom language tutorial will continue using
DocumentationProvider
.
{title="Targeting IDEs before 2023.1" style="note"}
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.
- 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.
- {style="full"}
DocumentationTargetProvider
- Implement
DocumentationTargetProvider
and register it ascom.intellij.platform.backend.documentation.targetProvider
extension point to build documentation for a certain offset in aPsiFile
by overridingdocumentationTargets()
. PsiDocumentationTargetProvider
- Implement
PsiDocumentationTargetProvider
and register it ascom.intellij.platform.backend.documentation.psiTargetProvider
extension point to build documentation for PSI elements by overridingdocumentationTarget()
. SymbolDocumentationTargetProvider
- Implement
SymbolDocumentationTargetProvider
and register it ascom.intellij.platform.backend.documentation.symbolTargetProvider
extension point to build documentation for by overridingdocumentationTarget()
.
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 API, 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
{#documentationtarget-api-examples}
KotlinPsiDocumentationTargetProvider
KotlinDocumentationTarget
PsiElementDocumentationTarget
Documentation Provider API
As of IntelliJ Platform version 2023.1, the Documentation Provider API is deprecated and plugin authors should use the instead.
{title="Deprecation Notice" style="note"}
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()
andExternalDocumentationProvider
to fetch documentation for elements from online resources.
Examples
{#documentationprovider-api-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 inThemeJsonDocumentationProvider
.
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.
Use
HtmlSyntaxInfoUtil
to create Lexer-based highlighted code samples.