[Analysis API] add KDocs to the substitution-related functionality

analysis/analysis-api-fir/src/org/jetbrains/kotlin/analysis/api/fir/types/KtFirSubstitutor.kt

@@ -5,6 +5,7 @@
 
 package org.jetbrains.kotlin.analysis.api.fir.types
 
+import org.jetbrains.kotlin.analysis.api.KtAnalysisApiInternals
 import org.jetbrains.kotlin.analysis.api.fir.KtSymbolByFirBuilder
 import org.jetbrains.kotlin.analysis.api.fir.utils.weakRef
 import org.jetbrains.kotlin.analysis.api.impl.base.KtMapBackedSubstitutor
@@ -36,6 +37,7 @@ internal class KtFirGenericSubstitutor(
     token: KtLifetimeToken
 ) : AbstractKtFirSubstitutor<ConeSubstitutor>(_substitutor, builder, token)
 
+@OptIn(KtAnalysisApiInternals::class)
 internal class KtFirMapBackedSubstitutor(
     _substitutor: ConeSubstitutorByMap,
     builder: KtSymbolByFirBuilder,

analysis/analysis-api-impl-base/src/org/jetbrains/kotlin/analysis/api/impl/base/KtMapBackedSubstitutor.kt

@@ -5,10 +5,19 @@
 
 package org.jetbrains.kotlin.analysis.api.impl.base
 
+import org.jetbrains.kotlin.analysis.api.KtAnalysisApiInternals
 import org.jetbrains.kotlin.analysis.api.symbols.KtTypeParameterSymbol
 import org.jetbrains.kotlin.analysis.api.types.KtSubstitutor
 import org.jetbrains.kotlin.analysis.api.types.KtType
 
+/**
+ * A [KtSubstitutor] which substitution logic can be represented as a [Map] from a [KtTypeParameterSymbol] to corresponding [KtType]
+ * This is an implementation details and Analysis API clients should not depend on the fact if some [KtSubstitutor] is [KtMapBackedSubstitutor] or not.
+ */
+@KtAnalysisApiInternals
 interface KtMapBackedSubstitutor : KtSubstitutor {
+    /**
+     * Substitution rules in a form of a `Map<KtTypeParameterSymbol, KtType>`
+     */
     fun getAsMap(): Map<KtTypeParameterSymbol, KtType>
 }

analysis/analysis-api-impl-base/src/org/jetbrains/kotlin/analysis/api/impl/base/components/AbstractKtSignatureSubstitutorImpl.kt

@@ -33,8 +33,8 @@ abstract class AbstractKtSignatureSubstitutorImpl : KtSignatureSubstitutor() {
         if (substitutor is KtSubstitutor.Empty) return signature
         return KtVariableLikeSignature(
             signature.symbol,
-            substitutor.substituteOrSelf(signature.returnType),
+            substitutor.substitute(signature.returnType),
-            signature.receiverType?.let { substitutor.substituteOrSelf(it) },
+            signature.receiverType?.let { substitutor.substitute(it) },
         )
     }
 
@@ -45,8 +45,8 @@ abstract class AbstractKtSignatureSubstitutorImpl : KtSignatureSubstitutor() {
         if (substitutor is KtSubstitutor.Empty) return signature
         return KtFunctionLikeSignature(
             signature.symbol,
-            substitutor.substituteOrSelf(signature.returnType),
+            substitutor.substitute(signature.returnType),
-            signature.receiverType?.let { substitutor.substituteOrSelf(it) },
+            signature.receiverType?.let { substitutor.substitute(it) },
             signature.valueParameters.map { substitute(it, substitutor) }
         )
     }
@@ -65,8 +65,8 @@ abstract class AbstractKtSignatureSubstitutorImpl : KtSignatureSubstitutor() {
         if (substitutor is KtSubstitutor.Empty) return asSignature(symbol)
         return KtFunctionLikeSignature(
             symbol,
-            substitutor.substituteOrSelf(symbol.returnType),
+            substitutor.substitute(symbol.returnType),
-            symbol.receiverType?.let { substitutor.substituteOrSelf(it) },
+            symbol.receiverType?.let { substitutor.substitute(it) },
             symbol.valueParameters.map { substitute(it, substitutor) }
         )
     }
@@ -75,8 +75,8 @@ abstract class AbstractKtSignatureSubstitutorImpl : KtSignatureSubstitutor() {
         if (substitutor is KtSubstitutor.Empty) return asSignature(symbol)
         return KtVariableLikeSignature(
             symbol,
-            substitutor.substituteOrSelf(symbol.returnType),
+            substitutor.substitute(symbol.returnType),
-            symbol.receiverType?.let { substitutor.substituteOrSelf(it) },
+            symbol.receiverType?.let { substitutor.substitute(it) },
         )
     }
 

analysis/analysis-api-impl-base/tests/org/jetbrains/kotlin/analysis/api/impl/base/test/cases/components/signatureSubstitution/AbstractAnalysisApiSignatureContractsTest.kt

@@ -102,13 +102,13 @@ abstract class AbstractAnalysisApiSignatureContractsTest : AbstractAnalysisApiSi
         substitutor: KtSubstitutor,
         testServices: TestServices
     ) {
-        testServices.assertions.assertEquals(symbol.receiverType?.let(substitutor::substituteOrSelf), signature.receiverType)
+        testServices.assertions.assertEquals(symbol.receiverType?.let(substitutor::substitute), signature.receiverType)
-        testServices.assertions.assertEquals(symbol.returnType.let(substitutor::substituteOrSelf), signature.returnType)
+        testServices.assertions.assertEquals(symbol.returnType.let(substitutor::substitute), signature.returnType)
 
         testServices.assertions.assertEquals(symbol.valueParameters.size, signature.valueParameters.size)
 
         for ((unsubstituted, substituted) in symbol.valueParameters.zip(signature.valueParameters)) {
-            testServices.assertions.assertEquals(substituted.returnType, unsubstituted.returnType.let(substitutor::substituteOrSelf))
+            testServices.assertions.assertEquals(substituted.returnType, unsubstituted.returnType.let(substitutor::substitute))
         }
     }
 
@@ -118,8 +118,8 @@ abstract class AbstractAnalysisApiSignatureContractsTest : AbstractAnalysisApiSi
         substitutor: KtSubstitutor,
         testServices: TestServices
     ) {
-        testServices.assertions.assertEquals(symbol.receiverType?.let(substitutor::substituteOrSelf), signature.receiverType)
+        testServices.assertions.assertEquals(symbol.receiverType?.let(substitutor::substitute), signature.receiverType)
-        testServices.assertions.assertEquals(symbol.returnType.let(substitutor::substituteOrSelf), signature.returnType)
+        testServices.assertions.assertEquals(symbol.returnType.let(substitutor::substitute), signature.returnType)
     }
 
     private fun <L> MutableList<List<L>>.combinations(list: List<L>, state: PersistentList<L>, size: Int) {

analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/components/KtSignatureSubstitutor.kt

@@ -45,39 +45,39 @@ public interface KtSignatureSubstitutorMixIn : KtAnalysisSessionMixIn {
     /**
      * Applies a [substitutor] to the given signature and return a new signature with substituted types.
      *
-     * @see KtSubstitutor.substituteOrSelf
+     * @see KtSubstitutor.substitute
      */
     public fun <S : KtCallableSymbol> KtCallableSignature<S>.substitute(substitutor: KtSubstitutor): KtCallableSignature<S> =
         withValidityAssertion { analysisSession.signatureSubstitutor.substitute(this, substitutor) }
 
     /**
-     * Applies a [substitutor]  to the given signature and return a new signature with substituted types.
+     * Applies a [substitutor] to the given signature and return a new signature with substituted types.
      *
-     * @see KtSubstitutor.substituteOrSelf
+     * @see KtSubstitutor.substitute
      */
     public fun <S : KtFunctionLikeSymbol> KtFunctionLikeSignature<S>.substitute(substitutor: KtSubstitutor): KtFunctionLikeSignature<S> =
         withValidityAssertion { analysisSession.signatureSubstitutor.substitute(this, substitutor) }
 
     /**
-     * Applies a [substitutor]  to the given signature and return a new signature with substituted types.
+     * Applies a [substitutor] to the given signature and return a new signature with substituted types.
      *
-     * @see KtSubstitutor.substituteOrSelf
+     * @see KtSubstitutor.substitute
      */
     public fun <S : KtVariableLikeSymbol> KtVariableLikeSignature<S>.substitute(substitutor: KtSubstitutor): KtVariableLikeSignature<S> =
         withValidityAssertion { analysisSession.signatureSubstitutor.substitute(this, substitutor) }
 
     /**
-     * Applies a [substitutor] to the given symbols and return a signature with substituted types.
+     * Applies a [substitutor] to the given symbol and return a signature with substituted types.
      *
-     * @see KtSubstitutor.substituteOrSelf
+     * @see KtSubstitutor.substitute
      */
     public fun <S : KtCallableSymbol> S.substitute(substitutor: KtSubstitutor): KtCallableSignature<S> =
         withValidityAssertion { analysisSession.signatureSubstitutor.substitute(this, substitutor) }
 
     /**
-     * Applies a [substitutor] to the given symbols and return a signature with substituted types.
+     * Applies a [substitutor] to the given symbol and return a signature with substituted types.
      *
-     * @see KtSubstitutor.substituteOrSelf
+     * @see KtSubstitutor.substitute
      */
     public fun <S : KtFunctionLikeSymbol> S.substitute(substitutor: KtSubstitutor): KtFunctionLikeSignature<S> =
         withValidityAssertion { analysisSession.signatureSubstitutor.substitute(this, substitutor) }
@@ -85,7 +85,7 @@ public interface KtSignatureSubstitutorMixIn : KtAnalysisSessionMixIn {
     /**
      * Applies a [substitutor] to the given symbols and return a signature with substituted types.
      *
-     * @see KtSubstitutor.substituteOrSelf
+     * @see KtSubstitutor.substitute
      */
     public fun <S : KtVariableLikeSymbol> S.substitute(substitutor: KtSubstitutor): KtVariableLikeSignature<S> =
         withValidityAssertion { analysisSession.signatureSubstitutor.substitute(this, substitutor) }

analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/components/KtSubstitutorFactory.kt

@@ -22,6 +22,9 @@ public abstract class KtSubstitutorFactory : KtAnalysisSessionComponent() {
     public abstract fun buildSubstitutor(builder: KtSubstitutorBuilder): KtSubstitutor
 }
 
+/**
+ * Creates new [KtSubstitutor] using substitutions specified inside [build] lambda
+ */
 @OptIn(ExperimentalContracts::class, KtAnalysisApiInternals::class)
 public inline fun KtAnalysisSession.buildSubstitutor(
     build: KtSubstitutorBuilder.() -> Unit
@@ -39,11 +42,20 @@ public class KtSubstitutorBuilder
 
     public val mappings: Map<KtTypeParameterSymbol, KtType> get() = withValidityAssertion { _mapping }
 
+    /**
+     * Adds a new [typeParameter] -> [type] substitution to the substitutor which is being built.
+     * If there already was a substitution with a [typeParameter], replaces corresponding substitution with a new one.
+     */
     public fun substitution(typeParameter: KtTypeParameterSymbol, type: KtType) {
         assertIsValidAndAccessible()
         _mapping[typeParameter] = type
     }
 
+    /**
+     * Adds a new substitutions to the substitutor which is being built.
+     * If there already was a substitution with a [KtTypeParameterSymbol] which is present in a [substitutions],
+     * replaces corresponding substitution with a new one.
+     */
     public fun substitutions(substitutions: Map<KtTypeParameterSymbol, KtType>) {
         assertIsValidAndAccessible()
         _mapping += substitutions

analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/signatures/KtCallableSignature.kt

@@ -38,6 +38,9 @@ public sealed class KtCallableSignature<out S : KtCallableSymbol> : KtLifetimeOw
      */
     public abstract val receiverType: KtType?
 
+    /**
+     * A [CallableId] of a substituted symbol
+     */
     public open val callableIdIfNonLocal: CallableId? get() = withValidityAssertion { symbol.callableIdIfNonLocal }
 
     abstract override fun equals(other: Any?): Boolean

analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/signatures/KtFunctionLikeSignature.kt

@@ -13,7 +13,7 @@ import org.jetbrains.kotlin.analysis.api.symbols.KtValueParameterSymbol
 import org.jetbrains.kotlin.analysis.api.types.KtType
 
 /**
- * A signature of a function-like symbol.
+ * A signature of a function-like symbol. This includes functions, getters, setters, lambdas, etc.
  */
 public class KtFunctionLikeSignature<out S : KtFunctionLikeSymbol>(
     private val _symbol: S,

analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/signatures/KtVariableLikeSignature.kt

@@ -19,7 +19,7 @@ import org.jetbrains.kotlin.utils.addToStdlib.runIf
 
 
 /**
- * A signature of a variable-like symbol.
+ * A signature of a variable-like symbol. This includes properties, enum entries local variables, etc.
  */
 public class KtVariableLikeSignature<out S : KtVariableLikeSymbol>(
     private val _symbol: S,

analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/types/KtSubstitutor.kt

@@ -9,12 +9,39 @@ import org.jetbrains.kotlin.analysis.api.lifetime.KtLifetimeOwner
 import org.jetbrains.kotlin.analysis.api.lifetime.KtLifetimeToken
 import org.jetbrains.kotlin.analysis.api.lifetime.withValidityAssertion
 
-
+/**
+ * Type substitutor. Performs substitution of a type parameters inside a type to some fixed type.
+ * Usually can be represented as a map from type parameter to it corresponding substitution.
+ *
+ * Example of a substitution:
+ * ```
+ * substitutor = { T -> Int, S -> Long }
+ * substitute(Map<T, S>, substitutor) = Map<Int, Long>
+ * ```
+ *
+ * Can be built by [org.jetbrains.kotlin.analysis.api.components.buildSubstitutor] or retrieved via a [org.jetbrains.kotlin.analysis.api.calls.KtCall]
+ */
 public interface KtSubstitutor : KtLifetimeOwner {
-    public fun substituteOrSelf(type: KtType): KtType = withValidityAssertion { substituteOrNull(type) ?: type }
+    /**
+     * substitutes type parameters in a given type corresponding to internal mapping rules.
+     *
+     * @return substituted type if there was at least one substitution, [type] itself if there was no type parameter to substitute
+     */
+    public fun substitute(type: KtType): KtType = withValidityAssertion { substituteOrNull(type) ?: type }
+
+    /**
+     * substitutes type parameters in a given type corresponding to internal mapping rules.
+     *
+     * @return substituted type if there was at least one substitution, `null` if there was no type parameter to substitute
+     */
     public fun substituteOrNull(type: KtType): KtType?
 
+    /**
+     * [KtSubstitutor] which does nothing on a type and always returns the type intact
+     */
     public class Empty(override val token: KtLifetimeToken) : KtSubstitutor {
-        override fun substituteOrNull(type: KtType): KtType = withValidityAssertion { type }
+        override fun substituteOrNull(type: KtType): KtType? = withValidityAssertion { null }
+
+        override fun substituteOrSelf(type: KtType): KtType = withValidityAssertion { type }
     }
 }