From 89fa9f9dcd348f28e0304b6e2de198870faf008b Mon Sep 17 00:00:00 2001
From: Daniil Ovchinnikov <daniil.ovchinnikov@jetbrains.com>
Date: Wed, 26 Feb 2020 17:53:11 +0300
Subject: [PATCH] rename PsiElement2Declaration factory methods to reflect
 their semantics; add docs

GitOrigin-RevId: ed04a96d426f68ee2b37e54896ca98a51a269803
---
 .../model/psi/impl/PsiElement2Declaration.java  | 17 ++++++++++++++---
 .../psi/impl/PsiElementDeclarationSearcher.kt   |  2 +-
 .../com/intellij/model/psi/impl/declarations.kt |  2 +-
 3 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/platform/lang-impl/src/com/intellij/model/psi/impl/PsiElement2Declaration.java b/platform/lang-impl/src/com/intellij/model/psi/impl/PsiElement2Declaration.java
index e43c964a893c..5bda6e0fcec7 100644
--- a/platform/lang-impl/src/com/intellij/model/psi/impl/PsiElement2Declaration.java
+++ b/platform/lang-impl/src/com/intellij/model/psi/impl/PsiElement2Declaration.java
@@ -46,8 +46,13 @@ class PsiElement2Declaration implements PsiSymbolDeclaration {
     return myDeclarationRange;
   }
 
+  /**
+   * Adapts target element of unknown origin to a {@code PsiSymbolDeclaration}.
+   * E.g. when searching for declarations of a {@link Psi2Symbol PsiElement symbol} we lose info about origin,
+   * because the symbol could be obtained from reference or another declaration or any other old code.
+   */
   @Nullable
-  static PsiSymbolDeclaration createFromPsi(@NotNull PsiElement targetElement) {
+  static PsiSymbolDeclaration createFromTargetPsiElement(@NotNull PsiElement targetElement) {
     if (targetElement instanceof PsiNameIdentifierOwner) {
       PsiElement identifyingElement = ((PsiNameIdentifierOwner)targetElement).getIdentifyingElement();
       if (identifyingElement != null) {
@@ -57,9 +62,15 @@ class PsiElement2Declaration implements PsiSymbolDeclaration {
     return null;
   }
 
+  /**
+   * Adapts target element obtained from an element at caret to a {@code PsiSymbolDeclaration}.
+   *
+   * @param declaredElement  target element (symbol); used for target-based actions, e.g. Find Usages
+   * @param declaringElement element at caret from which {@code declaredElement} was obtained; used to determine the declaration range
+   */
   @NotNull
-  static PsiSymbolDeclaration createFromPsi(@NotNull PsiElement targetElement, @NotNull PsiElement declaringElement) {
-    return new PsiElement2Declaration(targetElement, declaringElement, getDeclarationRangeFromPsi(declaringElement));
+  static PsiSymbolDeclaration createFromDeclaredPsiElement(@NotNull PsiElement declaredElement, @NotNull PsiElement declaringElement) {
+    return new PsiElement2Declaration(declaredElement, declaringElement, getDeclarationRangeFromPsi(declaringElement));
   }
 
   @NotNull
diff --git a/platform/lang-impl/src/com/intellij/model/psi/impl/PsiElementDeclarationSearcher.kt b/platform/lang-impl/src/com/intellij/model/psi/impl/PsiElementDeclarationSearcher.kt
index e80869455126..e589b79daa25 100644
--- a/platform/lang-impl/src/com/intellij/model/psi/impl/PsiElementDeclarationSearcher.kt
+++ b/platform/lang-impl/src/com/intellij/model/psi/impl/PsiElementDeclarationSearcher.kt
@@ -44,7 +44,7 @@ class PsiElementDeclarationSearcher : PsiSymbolDeclarationSearcher {
 
   private fun fromPsiElement(psi: PsiElement, searchScope: SearchScope): PsiSymbolDeclaration? {
     if (psi in searchScope) {
-      return PsiElement2Declaration.createFromPsi(psi)
+      return PsiElement2Declaration.createFromTargetPsiElement(psi)
     }
     else {
       return null
diff --git a/platform/lang-impl/src/com/intellij/model/psi/impl/declarations.kt b/platform/lang-impl/src/com/intellij/model/psi/impl/declarations.kt
index c844211e2231..65fcfe3a6864 100644
--- a/platform/lang-impl/src/com/intellij/model/psi/impl/declarations.kt
+++ b/platform/lang-impl/src/com/intellij/model/psi/impl/declarations.kt
@@ -30,7 +30,7 @@ fun PsiFile.allDeclarationsAround(offsetInFile: Int): Collection<PsiSymbolDeclar
   for ((leaf, _) in leavesAroundOffset(offsetInFile)) {
     val namedElement: PsiElement? = TargetElementUtil.getNamedElement(leaf)
     if (namedElement != null) {
-      return listOf(PsiElement2Declaration.createFromPsi(namedElement, leaf))
+      return listOf(PsiElement2Declaration.createFromDeclaredPsiElement(namedElement, leaf))
     }
   }
   return emptyList()