Package com.intellij.lang.documentation

Interface DocumentationProvider

All Known Subinterfaces:

CodeDocumentationProvider

All Known Implementing Classes:

AbstractDocumentationProvider, AntDomDocumentationProvider, CommandLineDocumentationProvider, CompositeDocumentationProvider, DocumentationProviderEx, DomDocumentationProvider, GroovyDocumentationProvider, HtmlDocumentationProvider, ImageDocumentationProvider, InspectionDescriptionDocumentationProvider, JavaDocumentationProvider, JsonSchemaDocumentationProvider, LiveTemplateDocumentationProvider, PropertiesDocumentationProvider, PydevDocumentationProvider, PythonDocumentationProvider, PythonExternalDocumentationProvider, RegExpDocumentationProvider, RngCompactLanguage.MyDocumentationProvider, RngDocumentationProvider, ShDocumentationProvider, StructuralSearchTemplateDocumentationProvider, TaskDocumentationProvider, WebReferenceDocumentationProvider, XHtmlDocumentationProvider, XmlDocumentationProvider, XsltDocumentationProvider, YamlDocumentationProviderBase, YamlJsonSchemaDocumentationProvider

public interface DocumentationProvider

Provides documentation for PSI elements.

Extend AbstractDocumentationProvider.

See Also:

LanguageDocumentation, DocumentationProviderEx, ExternalDocumentationProvider, ExternalDocumentationHandler

Field Summary

Fields

Modifier and Type	Field and Description
static ExtensionPointName<DocumentationProvider>	EP_NAME Please use LanguageDocumentation instead of this for language-specific documentation

Method Summary

Modifier and Type	Method and Description
default void	collectDocComments(PsiFile file, java.util.function.Consumer<PsiDocCommentBase> sink) This defines documentation comments in file, which can be rendered in place.
default java.lang.String	generateDoc(PsiElement element, PsiElement originalElement) Callback for asking the doc provider for the complete documentation.
default java.lang.String	generateHoverDoc(PsiElement element, PsiElement originalElement) Same as generateDoc(PsiElement, PsiElement), but used for documentation showed on mouse hover in editor.
default java.lang.String	generateRenderedDoc(PsiElement element) This is used to display rendered documentation in editor, in place of corresponding documentation comment's text.
default PsiElement	getCustomDocumentationElement(Editor editor, PsiFile file, PsiElement contextElement, int targetOffset) Override this method if standard platform's choice for target PSI element to show documentation for (element either declared or referenced at target offset) isn't suitable for your language.
default PsiElement	getDocumentationElementForLink(PsiManager psiManager, java.lang.String link, PsiElement context) Returns the target element for a link in a documentation comment.
default PsiElement	getDocumentationElementForLookupItem(PsiManager psiManager, java.lang.Object object, PsiElement element)
default java.lang.String	getQuickNavigateInfo(PsiElement element, PsiElement originalElement) Returns the text to show in the Ctrl-hover popup for the specified element.
default java.util.List<java.lang.String>	getUrlFor(PsiElement element, PsiElement originalElement) Returns the list of possible URLs to show as external documentation for the specified element.

Field Detail

EP_NAME

static final ExtensionPointName<DocumentationProvider> EP_NAME

Please use LanguageDocumentation instead of this for language-specific documentation

Method Detail

getQuickNavigateInfo

default java.lang.String getQuickNavigateInfo(PsiElement element,
                                              PsiElement originalElement)

Returns the text to show in the Ctrl-hover popup for the specified element.

Parameters:

element - the element for which the documentation is requested (for example, if the mouse is over a method reference, this will be the method to which the reference is resolved).

originalElement - the element under the mouse cursor

Returns:

the documentation to show, or null if the provider can't provide any documentation for this element. Documentation can contain HTML markup. If HTML special characters need to be shown in popup, they should be properly escaped.

getUrlFor

default java.util.List<java.lang.String> getUrlFor(PsiElement element,
                                                   PsiElement originalElement)

Returns the list of possible URLs to show as external documentation for the specified element.

Parameters:

element - the element for which the documentation is requested (for example, if the mouse is over a method reference, this will be the method to which the reference is resolved).

originalElement - the element under the mouse cursor

Returns:

the list of URLs to open in the browser or to use for showing documentation internally (ExternalDocumentationProvider). If the list contains a single URL, it will be opened. If the list contains multiple URLs, the user will be prompted to choose one of them. For ExternalDocumentationProvider, first URL, yielding non-empty result in ExternalDocumentationProvider.fetchExternalDocumentation(Project, PsiElement, List) will be used.

generateDoc

default java.lang.String generateDoc(PsiElement element,
                                     PsiElement originalElement)

Callback for asking the doc provider for the complete documentation. Underlying implementation may be time-consuming, that's why this method is expected not to be called from EDT.

One can use DocumentationMarkup to get proper content layout. Typical sample will look like this:

 DEFINITION_START + definition + DEFINITION_END +
 CONTENT_START + main description + CONTENT_END +
 SECTIONS_START +
   SECTION_HEADER_START + section name +
     SECTION_SEPARATOR + "<p>" + section content + SECTION_END +
   ... +
 SECTIONS_END
 

To show different content on mouse hover in editor, generateHoverDoc(PsiElement, PsiElement) should be implemented.

Parameters:

element - the element for which the documentation is requested (for example, if the mouse is over a method reference, this will be the method to which the reference is resolved).

originalElement - the element under the mouse cursor

Returns:

target element's documentation, or null if provider is unable to generate documentation for the given element

generateHoverDoc

default java.lang.String generateHoverDoc(PsiElement element,
                                          PsiElement originalElement)

Same as generateDoc(PsiElement, PsiElement), but used for documentation showed on mouse hover in editor.

At the moment it's only invoked to get initial on-hover documentation. If user navigates any link in that documentation, generateDoc(PsiElement, PsiElement) will be used to fetch corresponding content.

generateRenderedDoc

default java.lang.String generateRenderedDoc(PsiElement element)

This is used to display rendered documentation in editor, in place of corresponding documentation comment's text. Documentation comment PSI elements should implement PsiDocCommentBase for this functionality to work. Value returned by PsiDocCommentBase.getOwner() will be passed as element parameter to this method.

See Also:

collectDocComments(PsiFile, Consumer)

collectDocComments

default void collectDocComments(PsiFile file,
                                java.util.function.Consumer<PsiDocCommentBase> sink)

This defines documentation comments in file, which can be rendered in place. HTML content to be displayed will be obtained using generateRenderedDoc(PsiElement) method.

getDocumentationElementForLookupItem

default PsiElement getDocumentationElementForLookupItem(PsiManager psiManager,
                                                        java.lang.Object object,
                                                        PsiElement element)

getDocumentationElementForLink

default PsiElement getDocumentationElementForLink(PsiManager psiManager,
                                                  java.lang.String link,
                                                  PsiElement context)

Returns the target element for a link in a documentation comment. The link needs to use the DocumentationManagerProtocol.PSI_ELEMENT_PROTOCOL protocol.

Parameters:

psiManager - the PSI manager for the project in which the documentation is requested.

link - the text of the link, not including the protocol.

context - the element from which the navigation is performed.

Returns:

the navigation target, or null if the link couldn't be resolved.

See Also:

DocumentationManagerUtil.createHyperlink(StringBuilder, String, String, boolean)

getCustomDocumentationElement

default PsiElement getCustomDocumentationElement(Editor editor,
                                                 PsiFile file,
                                                 PsiElement contextElement,
                                                 int targetOffset)

Override this method if standard platform's choice for target PSI element to show documentation for (element either declared or referenced at target offset) isn't suitable for your language. For example, it could be a keyword where there's no PsiReference, but for which users might benefit from context help.

Parameters:

targetOffset - equals to caret offset for 'Quick Documentation' action, and to offset under mouse cursor for documentation shown on mouse hover

contextElement - the leaf PSI element in file at target offset

Returns:

target PSI element to show documentation for, or null if it should be determined by standard platform's logic (default behaviour)