Add documentation on type checker context / type system context

core/compiler.common/src/org/jetbrains/kotlin/types/AbstractTypeChecker.kt

@@ -12,7 +12,15 @@ import org.jetbrains.kotlin.utils.SmartList
 import org.jetbrains.kotlin.utils.SmartSet
 import java.util.*
 
-
+/**
+ * Context that defines how type-checker operates, stores type-checker state,
+ * created by [TypeCheckerProviderContext.newBaseTypeCheckerContext] in most cases
+ *
+ * Stateful and shouldn't be reused
+ *
+ * Once some type-checker operation is performed using a [TypeCheckerProviderContext], for example a [AbstractTypeChecker.isSubtypeOf],
+ * new instance of particular [AbstractTypeCheckerContext] should be created, with properly specified type system context
+ */
 abstract class AbstractTypeCheckerContext() {
 
     abstract val typeSystemContext: TypeSystemContext

core/compiler.common/src/org/jetbrains/kotlin/types/model/TypeSystemContext.kt

@@ -61,6 +61,9 @@ interface TypeSystemOptimizationContext {
     fun identicalArguments(a: SimpleTypeMarker, b: SimpleTypeMarker) = false
 }
 
+/**
+ * Context that allow type-impl agnostic access to common types
+ */
 interface TypeSystemBuiltInsContext {
     fun nullableNothingType(): SimpleTypeMarker
     fun nullableAnyType(): SimpleTypeMarker
@@ -68,6 +71,9 @@ interface TypeSystemBuiltInsContext {
     fun anyType(): SimpleTypeMarker
 }
 
+/**
+ * Context that allow construction of types
+ */
 interface TypeSystemTypeFactoryContext {
     fun createFlexibleType(lowerBound: SimpleTypeMarker, upperBound: SimpleTypeMarker): KotlinTypeMarker
     fun createSimpleType(
@@ -85,7 +91,10 @@ interface TypeSystemTypeFactoryContext {
     fun createErrorTypeWithCustomConstructor(debugName: String, constructor: TypeConstructorMarker): KotlinTypeMarker
 }
 
-
+/**
+ * Factory, that constructs [AbstractTypeCheckerContext], which defines type-checker behaviour
+ * Implementation is recommended to be [TypeSystemContext]
+ */
 interface TypeCheckerProviderContext {
     fun newBaseTypeCheckerContext(
         errorTypesEqualToAnything: Boolean,
@@ -93,6 +102,9 @@ interface TypeCheckerProviderContext {
     ): AbstractTypeCheckerContext
 }
 
+/**
+ * Extended type system context, which defines set of operations specific to common super-type calculation
+ */
 interface TypeSystemCommonSuperTypesContext : TypeSystemContext, TypeSystemTypeFactoryContext, TypeCheckerProviderContext {
 
     fun KotlinTypeMarker.anySuperTypeConstructor(predicate: (TypeConstructorMarker) -> Boolean) =
@@ -130,6 +142,9 @@ interface TypeSystemCommonSuperTypesContext : TypeSystemContext, TypeSystemTypeF
 // component implementation for TypeSystemInferenceExtensionContext
 interface TypeSystemInferenceExtensionContextDelegate : TypeSystemInferenceExtensionContext
 
+/**
+ * Extended type system context, which defines set of type operations specific for type inference
+ */
 interface TypeSystemInferenceExtensionContext : TypeSystemContext, TypeSystemBuiltInsContext, TypeSystemCommonSuperTypesContext {
     fun KotlinTypeMarker.contains(predicate: (KotlinTypeMarker) -> Boolean): Boolean
 
@@ -228,7 +243,9 @@ interface TypeSystemInferenceExtensionContext : TypeSystemContext, TypeSystemBui
 
 class ArgumentList(initialSize: Int) : ArrayList<TypeArgumentMarker>(initialSize), TypeArgumentListMarker
 
-
+/**
+ * Defines common kotlin type operations with types for abstract types
+ */
 interface TypeSystemContext : TypeSystemOptimizationContext {
     fun KotlinTypeMarker.asSimpleType(): SimpleTypeMarker?
     fun KotlinTypeMarker.asFlexibleType(): FlexibleTypeMarker?