Package com.intellij.lang.documentation

Class CompositeDocumentationProvider

java.lang.Object

com.intellij.lang.documentation.CompositeDocumentationProvider

All Implemented Interfaces:

DocumentationProvider, ExternalDocumentationHandler, ExternalDocumentationProvider

public class CompositeDocumentationProvider
extends java.lang.Object
implements DocumentationProvider, ExternalDocumentationProvider, ExternalDocumentationHandler

Field Summary

Fields inherited from interface com.intellij.lang.documentation.DocumentationProvider

EP_NAME

Method Summary

Modifier and Type	Method and Description
boolean	canFetchDocumentationLink(java.lang.String link)
boolean	canPromptToConfigureDocumentation(PsiElement element) Checks if the provider is capable of asking the user to configure external documentation for an element.
void	collectDocComments(PsiFile file, java.util.function.Consumer<PsiDocCommentBase> sink) This defines documentation comments in file, which can be rendered in place.
java.lang.String	fetchExternalDocumentation(Project project, PsiElement element, java.util.List<java.lang.String> docUrls)
java.lang.String	fetchExternalDocumentation(java.lang.String link, PsiElement element)
java.lang.String	generateDoc(PsiElement element, PsiElement originalElement) Callback for asking the doc provider for the complete documentation.
java.lang.String	generateHoverDoc(PsiElement element, PsiElement originalElement) Same as DocumentationProvider.generateDoc(PsiElement, PsiElement), but used for documentation showed on mouse hover in editor.
java.lang.String	generateRenderedDoc(PsiElement element) This is used to display rendered documentation in editor, in place of corresponding documentation comment's text.
java.util.List<DocumentationProvider>	getAllProviders()
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.
PsiElement	getDocumentationElementForLink(PsiManager psiManager, java.lang.String link, PsiElement context) Returns the target element for a link in a documentation comment.
PsiElement	getDocumentationElementForLookupItem(PsiManager psiManager, java.lang.Object object, PsiElement element)
CodeDocumentationProvider	getFirstCodeDocumentationProvider()
java.util.List<DocumentationProvider>	getProviders()
java.lang.String	getQuickNavigateInfo(PsiElement element, PsiElement originalElement) Returns the text to show in the Ctrl-hover popup for the specified element.
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.
boolean	handleExternal(PsiElement element, PsiElement originalElement)
boolean	handleExternalLink(PsiManager psiManager, java.lang.String link, PsiElement context)
boolean	hasDocumentationFor(PsiElement element, PsiElement originalElement) Quick check for existence of external documentation for specified element.
static boolean	hasUrlsFor(DocumentationProvider provider, PsiElement element, PsiElement originalElement)
void	promptToConfigureDocumentation(PsiElement element) Prompts the user to configure the external documentation for an element if none was found.
java.lang.String	toString()
static DocumentationProvider	wrapProviders(java.util.Collection<? extends DocumentationProvider> providers)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.intellij.lang.documentation.ExternalDocumentationHandler

canHandleExternal, extractRefFromLink

Method Detail

wrapProviders

public static DocumentationProvider wrapProviders(java.util.Collection<? extends DocumentationProvider> providers)

getAllProviders

public java.util.List<DocumentationProvider> getAllProviders()

getProviders

public java.util.List<DocumentationProvider> getProviders()

handleExternal

public boolean handleExternal(PsiElement element,
                              PsiElement originalElement)

Specified by:

handleExternal in interface ExternalDocumentationHandler

handleExternalLink

public boolean handleExternalLink(PsiManager psiManager,
                                  java.lang.String link,
                                  PsiElement context)

Specified by:

handleExternalLink in interface ExternalDocumentationHandler

canFetchDocumentationLink

public boolean canFetchDocumentationLink(java.lang.String link)

Specified by:

canFetchDocumentationLink in interface ExternalDocumentationHandler

fetchExternalDocumentation

public java.lang.String fetchExternalDocumentation(java.lang.String link,
                                                   PsiElement element)

Specified by:

fetchExternalDocumentation in interface ExternalDocumentationHandler

getQuickNavigateInfo

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

Description copied from interface: DocumentationProvider

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

Specified by:

getQuickNavigateInfo in interface DocumentationProvider

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

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

Description copied from interface: DocumentationProvider

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

Specified by:

getUrlFor in interface DocumentationProvider

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

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

Description copied from interface: DocumentationProvider

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, DocumentationProvider.generateHoverDoc(PsiElement, PsiElement) should be implemented.

Specified by:

generateDoc in interface DocumentationProvider

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

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

Description copied from interface: DocumentationProvider

Same as DocumentationProvider.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, DocumentationProvider.generateDoc(PsiElement, PsiElement) will be used to fetch corresponding content.

Specified by:

generateHoverDoc in interface DocumentationProvider

generateRenderedDoc

public java.lang.String generateRenderedDoc(PsiElement element)

Description copied from interface: DocumentationProvider

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.

Specified by:

generateRenderedDoc in interface DocumentationProvider

See Also:

DocumentationProvider.collectDocComments(PsiFile, Consumer)

collectDocComments

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

Description copied from interface: DocumentationProvider

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

Specified by:

collectDocComments in interface DocumentationProvider

getDocumentationElementForLookupItem

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

Specified by:

getDocumentationElementForLookupItem in interface DocumentationProvider

getDocumentationElementForLink

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

Description copied from interface: DocumentationProvider

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

Specified by:

getDocumentationElementForLink in interface DocumentationProvider

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)

getFirstCodeDocumentationProvider

public CodeDocumentationProvider getFirstCodeDocumentationProvider()

fetchExternalDocumentation

public java.lang.String fetchExternalDocumentation(Project project,
                                                   PsiElement element,
                                                   java.util.List<java.lang.String> docUrls)

Specified by:

fetchExternalDocumentation in interface ExternalDocumentationProvider

hasDocumentationFor

public boolean hasDocumentationFor(PsiElement element,
                                   PsiElement originalElement)

Description copied from interface: ExternalDocumentationProvider

Quick check for existence of external documentation for specified element. Called from action update, so must be fast. If not implemented, update check is performed by calling DocumentationProvider.getUrlFor(PsiElement, PsiElement).

Specified by:

hasDocumentationFor in interface ExternalDocumentationProvider

Parameters:

element - the element to check for existence of documentation

originalElement - the element at caret (on which the action was invoked)

Returns:

true if the external documentation action should be enabled, false otherwise.

canPromptToConfigureDocumentation

public boolean canPromptToConfigureDocumentation(PsiElement element)

Description copied from interface: ExternalDocumentationProvider

Checks if the provider is capable of asking the user to configure external documentation for an element.

Specified by:

canPromptToConfigureDocumentation in interface ExternalDocumentationProvider

Parameters:

element - the element for which no documentation was found

Returns:

true if the element is applicable to this provider and the provider has a UI to configure the documentation location, false otherwise

promptToConfigureDocumentation

public void promptToConfigureDocumentation(PsiElement element)

Description copied from interface: ExternalDocumentationProvider

Prompts the user to configure the external documentation for an element if none was found.

Specified by:

promptToConfigureDocumentation in interface ExternalDocumentationProvider

Parameters:

element - the element for which no documentation was found

hasUrlsFor

public static boolean hasUrlsFor(DocumentationProvider provider,
                                 PsiElement element,
                                 PsiElement originalElement)

getCustomDocumentationElement

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

Description copied from interface: DocumentationProvider

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.

Specified by:

getCustomDocumentationElement in interface DocumentationProvider

contextElement - the leaf PSI element in file at target offset

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

Returns:

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

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object