references_and_resolve.md: cleanup

reference_guide/custom_language_support/references_and_resolve.md

@@ -4,9 +4,11 @@ title: References and Resolve
 
 One of the most important and tricky parts in implementing a custom language PSI is resolving references.
 Resolving references gives users the ability to navigate from a PSI element usage (accessing a variable, calling a method and so on) to the declaration of that element (the variable's definition, a method declaration and so on).
-This feature is needed in order to support the `Go to Declaration` action invoked by **Ctrl-B** and **Ctrl-Click**, and it is a prerequisite for implementing the `Find Usages` action, the `Rename` refactoring and code completion.
+This feature is needed in order to support the _Go to Declaration_ action invoked by **Ctrl-B** and **Ctrl-Click**, and it is a prerequisite for implementing the [Find Usages](find_usages.md) action, the [Rename Refactoring](rename_refactoring.md) and [Code Completion](code_completion.md).
 
-All PSI elements which work as references (for which the `Go to Declaration` action applies) need to implement the
+> **NOTE** The _Quick Definition_ action is based on the same mechanism, so it becomes automatically available for all references that can be resolved by the language plugin.
+
+All PSI elements which work as references (for which the _Go to Declaration_ action applies) need to implement the
 [`PsiElement.getReference()`](upsource:///platform/core-api/src/com/intellij/psi/PsiElement.java)
 method and to return a
 [`PsiReference`](upsource:///platform/core-api/src/com/intellij/psi/PsiReference.java)
@@ -23,18 +25,18 @@ The main method of the
 [`PsiReference`](upsource:///platform/core-api/src/com/intellij/psi/PsiReference.java)
 interface is `resolve()`, which returns the element to which the reference points, or `null` if it was not possible to resolve the reference to a valid element (for example, should it point to an undefined class). The resolved element should implement the [`PsiNamedElement`](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java) interface.
 
-> **NOTE** While both the referencing element and the referenced element both have a name, only the element which **introduces** the name (e.g. the definition `int x = 42`) needs to implement the [`PsiNamedElement`](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java) interface. It is not necessary for the referencing element at the point of usage (e.g. the `x` in the expression `x + 1`) to implement [PsiNamedElement](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java).
+> **NOTE** While both the referencing element and the referenced element both have a name, only the element which **introduces** the name (e.g. the definition `int x = 42`) needs to implement the [`PsiNamedElement`](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java) interface. It is not necessary for the referencing element at the point of usage (e.g. the `x` in the expression `x + 1`) to implement `PsiNamedElement`.
 
-> **TIP** In order to enable more advanced IntelliJ functionality, prefer implementing [`PsiNameIdentifierOwner`](upsource:///platform/core-api/src/com/intellij/psi/PsiNameIdentifierOwner.java) over [PsiNamedElement](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java) where possible.
+> **TIP** In order to enable more advanced IntelliJ functionality, prefer implementing [`PsiNameIdentifierOwner`](upsource:///platform/core-api/src/com/intellij/psi/PsiNameIdentifierOwner.java) over [`PsiNamedElement`](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java) where possible.
 
 A counterpart to the `resolve()` method is `isReferenceTo()`, which checks if the reference resolves to the specified element. The latter method can be implemented by calling `resolve()` and comparing the result with the passed PSI element, but additional optimizations are possible (for example, performing the tree walk only if the element text is equal to the text of the reference).
 
 
-**Example**:
-[Reference](upsource:///plugins/properties/src/com/intellij/lang/properties/ResourceBundleReference.java)
+**Examples**:
+- [Reference](upsource:///plugins/properties/src/com/intellij/lang/properties/ResourceBundleReference.java)
 to a ResourceBundle in the
 [Properties language plugin](upsource:///plugins/properties)
-
+- [Custom Language Support Tutorial: Reference Contributor](/tutorials/custom_language_support/reference_contributor.md)
 
 There's a set of interfaces which can be used as a base for implementing resolve support, namely the
 [`PsiScopeProcessor`](upsource:///platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java) interface and the
@@ -70,15 +72,15 @@ The implementation of resolve based on the standard helper classes contains of t
    [`PsiScopeProcessor`](upsource:///platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java)
    to its child elements.
 
+### Resolving to Multiple Targets
 An extension of the
 [`PsiReference`](upsource:///platform/core-api/src/com/intellij/psi/PsiReference.java)
 interface, which allows a reference to resolve to multiple targets, is the
 [`PsiPolyVariantReference`](upsource:///platform/core-api/src/com/intellij/psi/PsiPolyVariantReference.java)
 interface.
 The targets to which the reference resolves are returned from the `multiResolve()` method.
-The `Go to Declaration` action for such references allows the user to choose a navigation target.
+The _Go to Declaration_ action for such references allows the user to choose a navigation target.
 The implementation of `multiResolve()` can be also based on
 [`PsiScopeProcessor`](upsource:///platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java),
 and can collect all valid targets for the reference instead of stopping when the first valid target is found.
 
-The `Quick Definition Lookup` action is based on the same mechanism as `Go to Declaration`, so it becomes automatically available for all references that can be resolved by the language plugin.