hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-28 01:07:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update Symbol API docs for 2021.2 (#611)

Browse Source 
* clean up

* update Symbol API docs for 2021.2
This commit is contained in:
Daniil Ovchinnikov 2021-11-17 17:15:36 +01:00 committed by GitHub
parent 9baca27a37
commit 0be97abd25
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 28 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
topics/reference_guide/custom_language_support/declarations_and_references.md
View File

@ -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).
To provide an Implicit reference, implement and register
[`ImplicitReferenceProvider`](upsource:///platform/core-api/src/com/intellij/model/psi/ImplicitReferenceProvider.java).

24
topics/reference_guide/custom_language_support/navigation.md
View File

@ -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).
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).