From 3ea2232591aa39d0c08f5fb7746f76ca446b4bcb Mon Sep 17 00:00:00 2001
From: Ilya Kirillov <ilya.kirillov@jetbrains.com>
Date: Mon, 13 Jun 2022 16:50:35 +0200
Subject: [PATCH] [Analysis API] add KDocs for KtTypeScopeProvider

---
 .../api/components/KtScopeProvider.kt         | 20 +++++++++++++++++++
 .../kotlin/analysis/api/scopes/KtTypeScope.kt | 10 +++++++---
 2 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/components/KtScopeProvider.kt b/analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/components/KtScopeProvider.kt
index d85f9c05544..aa2fb3a606b 100644
--- a/analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/components/KtScopeProvider.kt
+++ b/analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/components/KtScopeProvider.kt
@@ -65,6 +65,26 @@ public interface KtScopeProviderMixIn : KtAnalysisSessionMixIn {
     public fun List<KtScope>.asCompositeScope(): KtScope =
         withValidityAssertion { analysisSession.scopeProvider.getCompositeScope(this) }
 
+    /**
+     * Return a [KtTypeScope] for a given [KtType].
+     * The type scope will include all members which are declared and callable on a given type.
+     *
+     * Comparing to the [KtScope], in the [KtTypeScope] all use-site type parameters are substituted.
+     *
+     * Consider the following code
+     * ```
+     * fun foo(list: List<String>) {
+     *      list // get KtTypeScope for it
+     * }
+     *```
+     *
+     * Inside the `LIST_KT_ELEMENT.getKtType().getTypeScope()` would contain the `get(i: Int): String` method with substituted type `T = String`
+     *
+     * @return type scope for the given type if given `KtType` is not error type, `null` otherwise.
+     *
+     * @see KtTypeScope
+     * @see KtTypeProviderMixIn.getKtType
+     */
     public fun KtType.getTypeScope(): KtTypeScope? =
         withValidityAssertion { analysisSession.scopeProvider.getTypeScope(this) }
 
diff --git a/analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/scopes/KtTypeScope.kt b/analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/scopes/KtTypeScope.kt
index 28e3c3aa794..c200e7b9f35 100644
--- a/analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/scopes/KtTypeScope.kt
+++ b/analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/scopes/KtTypeScope.kt
@@ -5,16 +5,20 @@
 
 package org.jetbrains.kotlin.analysis.api.scopes
 
-import org.jetbrains.kotlin.analysis.api.symbols.KtCallableSymbol
 import org.jetbrains.kotlin.analysis.api.symbols.KtClassifierSymbol
 import org.jetbrains.kotlin.analysis.api.symbols.KtConstructorSymbol
 import org.jetbrains.kotlin.analysis.api.signatures.KtCallableSignature
 
-
+/**
+ * A scope inside which use-site type-parameters of callable declarations may be substituted. Such declarations are represented as [KtCallableSignature].
+ *
+ * @see org.jetbrains.kotlin.analysis.api.components.KtScopeProviderMixIn.getTypeScope
+ * @see KtCallableSignature
+ */
 public interface KtTypeScope : KtScopeLike {
 
     /**
-     * Return a sequence of [KtCallableSymbol] which current scope contain if declaration name matches [nameFilter]
+     * Return a sequence of [KtCallableSignature] which current scope contain if declaration name matches [nameFilter].
      */
     public fun getCallableSignatures(nameFilter: KtScopeNameFilter = { true }): Sequence<KtCallableSignature<*>>