[Analysis API] improve getClassOrObjectSymbolByClassId/getTopLevelCallableSymbols

add kdocs, use better names

analysis/analysis-api-fe10/src/org/jetbrains/kotlin/analysis/api/descriptors/components/KtFe10SymbolProvider.kt

@@ -120,7 +120,7 @@ internal class KtFe10SymbolProvider(
         return descriptor.toKtClassSymbol(analysisContext)
     }
 
-    override fun getTopLevelCallableSymbols(packageFqName: FqName, name: Name): Sequence<KtSymbol> {
+    override fun getTopLevelCallableSymbols(packageFqName: FqName, name: Name): Sequence<KtCallableSymbol> {
         val packageViewDescriptor = analysisContext.resolveSession.moduleDescriptor.getPackage(packageFqName)
         return packageViewDescriptor.memberScope.getContributedDescriptors(DescriptorKindFilter.ALL, nameFilter = { it == name })
             .asSequence()

analysis/analysis-api-fir/src/org/jetbrains/kotlin/analysis/api/fir/components/KtFirInheritorsProvider.kt

@@ -28,7 +28,7 @@ internal class KtFirInheritorsProvider(
         val inheritorClassIds = classSymbol.firSymbol.fir.getSealedClassInheritors(analysisSession.useSiteSession)
 
         return with(analysisSession) {
-            inheritorClassIds.mapNotNull { it.getCorrespondingToplevelClassOrObjectSymbol() as? KtNamedClassOrObjectSymbol }
+            inheritorClassIds.mapNotNull { getClassOrObjectSymbolByClassId(it) as? KtNamedClassOrObjectSymbol }
         }
     }
 

analysis/analysis-api-fir/src/org/jetbrains/kotlin/analysis/api/fir/components/KtFirSymbolContainingDeclarationProvider.kt

@@ -39,7 +39,7 @@ internal class KtFirSymbolContainingDeclarationProvider(
             val classId = symbol.callableIdIfNonLocal?.classId
             if (classId != null) {
                 with(analysisSession) {
-                    return classId.getCorrespondingToplevelClassOrObjectSymbol()
+                    return getClassOrObjectSymbolByClassId(classId)
                 }
             }
         }
@@ -160,7 +160,7 @@ internal class KtFirSymbolContainingDeclarationProvider(
             }
             else -> error("We should not have a ${symbol::class} from a library")
         } ?: error("outerClassId should not be null for member declaration")
-        val containingClass = containingClassId.getCorrespondingToplevelClassOrObjectSymbol()
+        val containingClass = getClassOrObjectSymbolByClassId(containingClassId)
         return containingClass ?: error("Class by class id should exists")
     }
 }

analysis/analysis-api-fir/src/org/jetbrains/kotlin/analysis/api/fir/references/KDocReferenceResolver.kt

@@ -107,18 +107,18 @@ internal object KDocReferenceResolver {
 
     context(KtAnalysisSession)
     private fun MutableCollection<KtSymbol>.collectSymbolsByClassId(classId: ClassId) {
-        classId.getCorrespondingToplevelClassOrObjectSymbol()?.let(::add)
+        getClassOrObjectSymbolByClassId(classId)?.let(::add)
     }
 
     context(KtAnalysisSession)
     private fun MutableCollection<KtSymbol>.collectSymbolsByFqNameInterpretationAsCallableId(callableId: CallableId) {
         when (val classId = callableId.classId) {
             null -> {
-                addAll(callableId.packageName.getContainingCallableSymbolsWithName(callableId.callableName))
+                addAll(getTopLevelCallableSymbols(callableId.packageName, callableId.callableName))
             }
 
             else -> {
-                classId.getCorrespondingToplevelClassOrObjectSymbol()
+                getClassOrObjectSymbolByClassId(classId)
                     ?.getDeclaredMemberScope()
                     ?.getCallableSymbols { it == callableId.callableName }
                     ?.let(::addAll)

analysis/analysis-api-fir/src/org/jetbrains/kotlin/analysis/api/fir/symbols/KtFirSymbolProvider.kt

@@ -161,9 +161,11 @@ internal class KtFirSymbolProvider(
         return firSymbolBuilder.classifierBuilder.buildNamedClassOrObjectSymbol(symbol)
     }
 
-    override fun getTopLevelCallableSymbols(packageFqName: FqName, name: Name): Sequence<KtSymbol> {
+    override fun getTopLevelCallableSymbols(packageFqName: FqName, name: Name): Sequence<KtCallableSymbol> {
         val firs = firSymbolProvider.getTopLevelCallableSymbols(packageFqName, name)
-        return firs.asSequence().map { firSymbol -> firSymbolBuilder.buildSymbol(firSymbol) }
+        return firs.asSequence().map { firSymbol ->
+            firSymbolBuilder.buildSymbol(firSymbol) as KtCallableSymbol
+        }
     }
 
     override fun getPackageSymbolIfPackageExists(packageFqName: FqName): KtPackageSymbol? {

analysis/analysis-api-impl-base/tests/org/jetbrains/kotlin/analysis/api/impl/base/test/SymbolByFqName.kt

@@ -45,7 +45,7 @@ sealed class SymbolData {
 
     data class ClassData(val classId: ClassId) : SymbolData() {
         override fun KtAnalysisSession.toSymbols(): List<KtSymbol> {
-            val symbol = classId.getCorrespondingToplevelClassOrObjectSymbol() ?: error("Class $classId is not found")
+            val symbol = getClassOrObjectSymbolByClassId(classId) ?: error("Class $classId is not found")
             return listOf(symbol)
         }
     }
@@ -54,10 +54,10 @@ sealed class SymbolData {
         override fun KtAnalysisSession.toSymbols(): List<KtSymbol> {
             val classId = callableId.classId
             val symbols = if (classId == null) {
-                callableId.packageName.getContainingCallableSymbolsWithName(callableId.callableName).toList()
+                getTopLevelCallableSymbols(callableId.packageName, callableId.callableName).toList()
             } else {
                 val classSymbol =
-                    classId.getCorrespondingToplevelClassOrObjectSymbol()
+                    getClassOrObjectSymbolByClassId(classId)
                         ?: error("Class $classId is not found")
                 classSymbol.getDeclaredMemberScope().getCallableSymbols()
                     .filter { (it as? KtNamedSymbol)?.name == callableId.callableName }

analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/symbols/KtSymbolProvider.kt

@@ -55,7 +55,7 @@ public abstract class KtSymbolProvider : KtAnalysisSessionComponent() {
 
     public abstract fun getClassOrObjectSymbolByClassId(classId: ClassId): KtClassOrObjectSymbol?
 
-    public abstract fun getTopLevelCallableSymbols(packageFqName: FqName, name: Name): Sequence<KtSymbol>
+    public abstract fun getTopLevelCallableSymbols(packageFqName: FqName, name: Name): Sequence<KtCallableSymbol>
 
     @Suppress("PropertyName")
     public abstract val ROOT_PACKAGE_SYMBOL: KtPackageSymbol
@@ -138,11 +138,17 @@ public interface KtSymbolProviderMixIn : KtAnalysisSessionMixIn {
     /**
      * @return symbol with specified [this@getClassOrObjectSymbolByClassId] or `null` in case such symbol is not found
      */
-    public fun ClassId.getCorrespondingToplevelClassOrObjectSymbol(): KtClassOrObjectSymbol? =
-        withValidityAssertion { analysisSession.symbolProvider.getClassOrObjectSymbolByClassId(this) }
+    public fun getClassOrObjectSymbolByClassId(classId: ClassId): KtClassOrObjectSymbol? =
+        withValidityAssertion { analysisSession.symbolProvider.getClassOrObjectSymbolByClassId(classId) }
 
-    public fun FqName.getContainingCallableSymbolsWithName(name: Name): Sequence<KtSymbol> =
-        withValidityAssertion { analysisSession.symbolProvider.getTopLevelCallableSymbols(this, name) }
+    /**
+     * @return list of top-level functions and properties which are visible from current use-site module
+     *
+     * @param packageFqName package name in which callable symbols should be declared
+     * @param name callable symbol name
+     */
+    public fun getTopLevelCallableSymbols(packageFqName: FqName, name: Name): Sequence<KtCallableSymbol> =
+        withValidityAssertion { analysisSession.symbolProvider.getTopLevelCallableSymbols(packageFqName, name) }
 
     /**
      * @return symbol corresponding to the local variable introduced by individual destructuring declaration entries.

analysis/symbol-light-classes/src/org/jetbrains/kotlin/light/classes/symbol/classes/symbolLightClassUtils.kt

@@ -473,7 +473,7 @@ internal fun KtClassOrObject.checkIsInheritor(superClassOrigin: KtClassOrObject,
         is KtEnumEntry -> {
             val enumEntrySymbol = this.getEnumEntrySymbol()
             val classId = enumEntrySymbol.containingEnumClassIdIfNonLocal ?: return false
-            val enumClassSymbol = classId.getCorrespondingToplevelClassOrObjectSymbol() ?: return false
+            val enumClassSymbol = getClassOrObjectSymbolByClassId(classId) ?: return false
             if (enumClassSymbol == superClassSymbol) return true
             return if (checkDeep) {
                 enumClassSymbol.isSubClassOf(superClassSymbol)