From 0be97abd254a50f4dabbfd4ae987400f69e0815d Mon Sep 17 00:00:00 2001 From: Daniil Ovchinnikov <5519549+dovchinnikov@users.noreply.github.com> Date: Wed, 17 Nov 2021 17:15:36 +0100 Subject: [PATCH] Update Symbol API docs for 2021.2 (#611) * clean up * update Symbol API docs for 2021.2 --- .../declarations_and_references.md | 41 ++++++++----------- .../custom_language_support/navigation.md | 24 +++++------ 2 files changed, 28 insertions(+), 37 deletions(-) diff --git a/topics/reference_guide/custom_language_support/declarations_and_references.md b/topics/reference_guide/custom_language_support/declarations_and_references.md index 09d72b031..2e524e760 100644 --- a/topics/reference_guide/custom_language_support/declarations_and_references.md +++ b/topics/reference_guide/custom_language_support/declarations_and_references.md @@ -14,37 +14,28 @@ Each [symbol](symbols.md) may be declared in zero or more places, for example: - a Java local variable is a symbol with a single declaration; - and a file is a symbol without declarations; it has only references. -Declarations are implementations of -[`SymbolDeclaration`](upsource:///platform/core-api/src/com/intellij/model/SymbolDeclaration.java). Declarations in PSI elements are implementations of [`PsiSymbolDeclaration`](upsource:///platform/core-api/src/com/intellij/model/psi/PsiSymbolDeclaration.java). To report a declaration in a PSI element, either: -- implement and register +- implement and register [`PsiSymbolDeclarationProvider`](upsource:///platform/core-api/src/com/intellij/model/psi/PsiSymbolDeclarationProvider.java); - or implement `PsiSymbolDeclaration` directly in the `PsiElement`. ## References -References are implementations of -[`SymbolReference`](upsource:///platform/core-api/src/com/intellij/model/SymbolReference.java) interface. -References from PSI elements are implementations of +References from PSI elements are implementations of [`PsiSymbolReference`](upsource:///platform/core-api/src/com/intellij/model/psi/PsiSymbolReference.java) interface. -The main method of `SymbolReference` is `resolveReference()`, which returns the collection of symbols to which the reference points, +The main method of `PsiSymbolReference` is `resolveReference()`, which returns the collection of symbols to which the reference points, plus additional data. -If it is not possible to resolve the reference, for example, if it points to an undefined class, an empty collection gets returned. -A counterpart to the `resolveReference()` method is `SymbolReference.resolvesTo()`, -which checks if the reference resolves to the specified symbol. +If it is not possible to resolve the reference, for example, if it points to an undefined class, an empty collection gets returned. +A counterpart to the `resolveReference()` method is `PsiSymbolReference.resolvesTo()`, +which checks if the reference resolves to the specified symbol. This method can be implemented to walk the tree only if the element's text is equal to the reference's text. -For convenience, if the reference can possibly be resolved: -- with a single result, then it might be extended from -[`SingleResultReference`](upsource:///platform/core-api/src/com/intellij/model/SingleResultReference.java); -- to a single symbol without additional data, then it might be extended from -[`SingleTargetReference`](upsource:///platform/core-api/src/com/intellij/model/SingleTargetReference.java); -- to multiple symbols without additional data, then -[`SymbolResolveResult.fromSymbol()`](upsource:///platform/core-api/src/com/intellij/model/SymbolResolveResult.java) might be used. +For convenience, if the reference can possibly be resolved to a single symbol without additional data, then it might be extended from +[`SingleTargetReference`](upsource:///platform/core-api/src/com/intellij/model/SingleTargetReference.java). ### Own References @@ -54,13 +45,13 @@ Own references are the references found in PSI elements, which are considered as PSI element representing `x` in `x * 2` Java expression has an Own reference to a local Java variable, e.g., `var x = 42`, because this is a reference from Java language point of view, and Java language support uses it, e.g., for code analysis. -To provide Own references by the `PsiElement`, implement +To provide Own references by the `PsiElement`, implement [`PsiElement.getOwnReferences()`](upsource:///platform/core-api/src/com/intellij/psi/PsiElement.java) in the `PsiElement`. If the element contains a single reference, `Collections.singletonList()` can be used ### External References -External references are the references which are not considered as references by the host language. +External references are the references which are not considered as references by the host language. The language support should not rely on their existence/absence, because they might be contributed by other plugins. **Example:** @@ -68,14 +59,14 @@ PSI element representing `"users.txt"` in `new File("users.txt")` Java expressio but there is a plugin which _knows_ that this literal references a file name, and provides such reference. External references might be contributed to PSI elements -that implement [`PsiExternalReferenceHost`](upsource:///platform/core-api/src/com/intellij/model/psi/PsiExternalReferenceHost.java). -To allow other plugins to contribute references of `PsiElement`, implement `PsiExternalReferenceHost` in the `PsiElement`. -To contribute an External reference to the existing `PsiExternalReferenceHost`, implement and register +that implement [`PsiExternalReferenceHost`](upsource:///platform/core-api/src/com/intellij/model/psi/PsiExternalReferenceHost.java). +To allow other plugins to contribute references of `PsiElement`, implement `PsiExternalReferenceHost` in the `PsiElement`. +To contribute an External reference to the existing `PsiExternalReferenceHost`, implement and register [`PsiSymbolReferenceProvider`](upsource:///platform/core-api/src/com/intellij/model/psi/PsiSymbolReferenceProvider.java). ### Implicit References -Implicit references are the references which should be part of the mechanism to obtain a target by a reference, +Implicit references are the references which should be part of the mechanism to obtain a target by a reference, without the inverse ability to search or rename such references by a target. **Example:** @@ -85,5 +76,5 @@ At the same time it's possible: - to start a refactoring (e.g., rename) from the class targeted by this reference; - to view documentation of the class targeted by this reference. -To provide an Implicit reference, implement and register -[`ImplicitReferenceProvider`](upsource:///platform/core-api/src/com/intellij/model/psi/ImplicitReferenceProvider.java). \ No newline at end of file +To provide an Implicit reference, implement and register +[`ImplicitReferenceProvider`](upsource:///platform/core-api/src/com/intellij/model/psi/ImplicitReferenceProvider.java). diff --git a/topics/reference_guide/custom_language_support/navigation.md b/topics/reference_guide/custom_language_support/navigation.md index c28ba4516..0bef3c890 100644 --- a/topics/reference_guide/custom_language_support/navigation.md +++ b/topics/reference_guide/custom_language_support/navigation.md @@ -10,34 +10,34 @@ The _Go to Declaration or Usages_ action is performed in several steps. ## Direct Navigation -Direct navigation is the navigation from `PsiElement` to another `PsiElement`, +Direct navigation is the navigation from `PsiElement` to another `PsiElement`, such as navigation from `break` keyword to the end of a loop in Java, without showing any popups. -To provide `PsiElement` for direct navigation, implement and register +To provide `PsiElement` for direct navigation, implement and register [`DirectNavigationProvider`](upsource:///platform/core-api/src/com/intellij/navigation/DirectNavigationProvider.java). ## Symbol Navigation If there is no Direct navigation available under the caret, then the IntelliJ Platform proceeds with `Symbol` navigation. -In this step the IntelliJ Platform computes the navigation targets based on target symbols, -which it obtains by resolving a [reference](declarations_and_references.md#references). -If there are several target symbols or several navigation targets defined for a symbol, +In this step the IntelliJ Platform computes the navigation targets based on target symbols, +which it obtains by resolving a [reference](declarations_and_references.md#references). +If there are several target symbols or several navigation targets defined for a symbol, then the IDE shows the navigation popup to ask the user to choose where to go. The [`NavigationTarget`](upsource:///platform/core-api/src/com/intellij/navigation/NavigationTarget.java) -is essentially a pair of a `Navigatable` and -a [`TargetPopupPresentation.kt`](upsource:///platform/core-api/src/com/intellij/navigation/TargetPopupPresentation.kt) +is essentially a pair of a `Navigatable` and +a [`TargetPresentation`](upsource:///platform/core-api/src/com/intellij/navigation/TargetPresentation.kt) instances (where to go and what to show in the popup). To provide navigation targets by a `Symbol`, either: -- implement and register +- implement and register [`SymbolNavigationProvider`](upsource:///platform/core-api/src/com/intellij/navigation/SymbolNavigationProvider.java); -- or implement +- or implement [`NavigatableSymbol`](upsource:///platform/core-api/src/com/intellij/navigation/NavigatableSymbol.java) in the `Symbol`. ## Showing Usages -If there are no navigation targets available, then the IntelliJ Platform starts finding usages of the target symbol -obtained by resolving a [reference](declarations_and_references.md#references) -or from a [declaration](declarations_and_references.md#declarations). \ No newline at end of file +If there are no navigation targets available, then the IntelliJ Platform starts finding usages of the target symbol +obtained by resolving a [reference](declarations_and_references.md#references) +or from a [declaration](declarations_and_references.md#declarations).