Package com.intellij.lang.java

Class JavaDocumentationProvider

java.lang.Object

com.intellij.lang.java.JavaDocumentationProvider

All Implemented Interfaces:

CodeDocumentationProvider, DocumentationProvider, ExternalDocumentationProvider

public class JavaDocumentationProvider
extends java.lang.Object
implements CodeDocumentationProvider, ExternalDocumentationProvider

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	HTML_EXTENSION
static java.lang.String	PACKAGE_SUMMARY_FILE

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

EP_NAME

Constructor Summary

Constructors

Constructor and Description
JavaDocumentationProvider()

Method Summary

Modifier and Type	Method and Description
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.
static void	createTypeParamsListComment(java.lang.StringBuilder buffer, CodeDocumentationAwareCommenter commenter, PsiTypeParameterList typeParameterList)
java.lang.String	fetchExternalDocumentation(Project project, PsiElement element, java.util.List<java.lang.String> docUrls)
static java.lang.String	fetchExternalJavadoc(PsiElement element, java.util.List<java.lang.String> docURLs, JavaDocExternalFilter docFilter)
static java.lang.String	fetchExternalJavadoc(PsiElement element, Project project, java.util.List<java.lang.String> docURLs)
PsiComment	findExistingDocComment(PsiComment comment) Finds primary documentation comment within given context.
static java.util.List<java.lang.String>	findUrlForClass(PsiClass aClass)
static java.util.List<java.lang.String>	findUrlForPackage(PsiPackage aPackage)
static java.lang.String	generateClassInfo(PsiClass aClass)
java.lang.String	generateDoc(PsiElement element, PsiElement originalElement) Callback for asking the doc provider for the complete documentation.
java.lang.String	generateDocumentationContentStub(PsiComment _comment) Generate documentation comment content for given context.
static java.lang.String	generateExternalJavadoc(PsiElement element)
static java.lang.String	generateExternalJavadoc(PsiElement element, JavaDocInfoGenerator generator)
static java.lang.String	generateExternalJavadoc(PsiElement element, java.util.List<java.lang.String> docURLs)
static java.lang.String	generateMethodInfo(PsiMethod method, PsiSubstitutor substitutor)
static void	generateParametersTakingDocFromSuperMethods(java.lang.StringBuilder builder, CodeDocumentationAwareCommenter commenter, PsiMethod psiMethod)
java.lang.String	generateRenderedDoc(PsiElement element) This is used to display rendered documentation in editor, in place of corresponding documentation comment's text.
static void	generateTypeParameters(PsiTypeParameterListOwner typeParameterOwner, java.lang.StringBuilder buffer)
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.
static java.util.List<java.lang.String>	getExternalJavaDocUrl(PsiElement element)
static java.util.Set<java.lang.String>	getHtmlMethodSignatures(PsiMethod method, LanguageLevel preferredFormat)
static PsiDocComment	getPackageInfoComment(PsiElement packageInfoFile)
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	hasDocumentationFor(PsiElement element, PsiElement originalElement) Quick check for existence of external documentation for specified element.
Pair<PsiElement,PsiComment>	parseContext(PsiElement startPoint) Examines PSI hierarchy identified by the given 'start' element trying to find element which can be documented and it's doc comment (if any).
void	promptToConfigureDocumentation(PsiElement element) Prompts the user to configure the external documentation for an element if none was found.
static void	writeExtends(PsiClass aClass, java.lang.StringBuilder buffer, PsiClassType[] refs)
static void	writeImplements(PsiClass aClass, java.lang.StringBuilder buffer, PsiClassType[] refs)

Methods inherited from class java.lang.Object

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

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

generateHoverDoc, getDocumentationElementForLookupItem

Field Detail

HTML_EXTENSION

public static final java.lang.String HTML_EXTENSION

See Also:

Constant Field Values

PACKAGE_SUMMARY_FILE

public static final java.lang.String PACKAGE_SUMMARY_FILE

See Also:

Constant Field Values

Constructor Detail

JavaDocumentationProvider

public JavaDocumentationProvider()

Method Detail

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.

generateClassInfo

public static java.lang.String generateClassInfo(PsiClass aClass)

writeImplements

public static void writeImplements(PsiClass aClass,
                                   java.lang.StringBuilder buffer,
                                   PsiClassType[] refs)

writeExtends

public static void writeExtends(PsiClass aClass,
                                java.lang.StringBuilder buffer,
                                PsiClassType[] refs)

generateTypeParameters

public static void generateTypeParameters(PsiTypeParameterListOwner typeParameterOwner,
                                          java.lang.StringBuilder buffer)

generateMethodInfo

public static java.lang.String generateMethodInfo(PsiMethod method,
                                                  PsiSubstitutor substitutor)

findExistingDocComment

public PsiComment findExistingDocComment(PsiComment comment)

Description copied from interface: CodeDocumentationProvider

Finds primary documentation comment within given context.

Specified by:

findExistingDocComment in interface CodeDocumentationProvider

Parameters:

comment - candidate psi comment

Returns:

contextElement if no other applicable

parseContext

public Pair<PsiElement,PsiComment> parseContext(PsiElement startPoint)

Description copied from interface: CodeDocumentationProvider

Examines PSI hierarchy identified by the given 'start' element trying to find element which can be documented and it's doc comment (if any).

Example:

   int test() {
     return [caret] 1;
   }
 

PSI element at the caret (return element) is an entry point. This method is expected to return PSI method element and 'null' as the existing doc comment then.

Specified by:

parseContext in interface CodeDocumentationProvider

Parameters:

startPoint - start traversal point

Returns:

comment anchor which is a given element or its anchor if the one is found and its doc comment (if existing). This method may return 'null' as an indication that no doc comment anchor and existing comment is available; returned pair must have non-null PSI element and nullable existing comment references then

generateDocumentationContentStub

public java.lang.String generateDocumentationContentStub(PsiComment _comment)

Description copied from interface: CodeDocumentationProvider

Generate documentation comment content for given context.

Specified by:

generateDocumentationContentStub in interface CodeDocumentationProvider

Parameters:

_comment - context psi comment

Returns:

documentation content for given context if any

generateParametersTakingDocFromSuperMethods

public static void generateParametersTakingDocFromSuperMethods(java.lang.StringBuilder builder,
                                                               CodeDocumentationAwareCommenter commenter,
                                                               PsiMethod psiMethod)

createTypeParamsListComment

public static void createTypeParamsListComment(java.lang.StringBuilder buffer,
                                               CodeDocumentationAwareCommenter commenter,
                                               PsiTypeParameterList typeParameterList)

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

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

generateExternalJavadoc

public static java.lang.String generateExternalJavadoc(PsiElement element)

generateExternalJavadoc

public static java.lang.String generateExternalJavadoc(PsiElement element,
                                                       java.util.List<java.lang.String> docURLs)

generateExternalJavadoc

public static java.lang.String generateExternalJavadoc(PsiElement element,
                                                       JavaDocInfoGenerator generator)

getExternalJavaDocUrl

public static java.util.List<java.lang.String> getExternalJavaDocUrl(PsiElement element)

getHtmlMethodSignatures

public static java.util.Set<java.lang.String> getHtmlMethodSignatures(PsiMethod method,
                                                                      LanguageLevel preferredFormat)

getPackageInfoComment

public static PsiDocComment getPackageInfoComment(PsiElement packageInfoFile)

findUrlForClass

public static java.util.List<java.lang.String> findUrlForClass(PsiClass aClass)

findUrlForPackage

public static java.util.List<java.lang.String> findUrlForPackage(PsiPackage aPackage)

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)

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

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)

fetchExternalJavadoc

public static java.lang.String fetchExternalJavadoc(PsiElement element,
                                                    Project project,
                                                    java.util.List<java.lang.String> docURLs)

fetchExternalJavadoc

public static java.lang.String fetchExternalJavadoc(PsiElement element,
                                                    java.util.List<java.lang.String> docURLs,
                                                    JavaDocExternalFilter docFilter)