[FIR] add KDoc for FirResolvePhase

compiler/fir/tree/src/org/jetbrains/kotlin/fir/declarations/FirResolvePhase.kt

@@ -1,23 +1,172 @@
 /*
- * Copyright 2010-2023 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
 package org.jetbrains.kotlin.fir.declarations
 
+/**
+ * Compilation in the FIR compiler is performed in separate compiler phases.
+ *
+ * ### Modes
+ * There are two compiler modes:
+ * - The CLI mode (aka full resolution mode), the compiler executes all phases sequentially for all declarations.
+ *   This means that `A` phase processor will transform all declarations in the first round.
+ *   In the next round, `B` phase (which follows `A`) processor will transform all declarations.
+ *
+ * - The Analysis API mode (aka lazy resolution mode),
+ *   the compiler executes the requested phase [lazily][org.jetbrains.kotlin.fir.symbols.lazyResolveToPhase]
+ *   (on demand) for some particular declaration (not for all declarations in the opposite to the CLI mode).
+ *
+ * ### Contacts
+ * There are a few contacts for both modes:
+ * 1. All phases **must be executed only in the sequential manner**.
+ *   If the compiler wants to resolve some declaration to the phase [COMPILER_REQUIRED_ANNOTATIONS],
+ *   then it has to resolve it to all previous phases firstly: to the [RAW_FIR] phase,
+ *   then to the phase [IMPORTS] and only after that the compiler can execute the phase [COMPILER_REQUIRED_ANNOTATIONS].
+ *
+ * 2. The compiler **must not request and cannot rely on the information from the higher phases**.
+ *   For example, during the [STATUS] phase,
+ *   we cannot have information regarding implicit types as they will be calculated only during [IMPLICIT_TYPES_BODY_RESOLVE] phase.
+ *
+ * 3. The compiler **can request and rely on the information from the current phase only during *jumping phases***.
+ *   For example, during the [TYPES] phase,
+ *   we cannot request type information for other declarations (except information from the [SUPER_TYPES] phase like a super type)
+ *   as this information will be calculated only during this phase.
+ *
+ * ### Jumping phases
+ * *Jumping phase* – it is a phase that can request the information from the same phase from another declaration.
+ *
+ * Currently, we have four ***jumping phases***:
+ * - [COMPILER_REQUIRED_ANNOTATIONS] – The compiler can jump from the use side of an annotation to the annotation class
+ *   and resolve its annotations as well.
+ * - [SUPER_TYPES] – The compiler resolves super types recursively for all classes from the bottom class to the top one.
+ * - [STATUS] – The compiler has to resolve the status for super declarations firstly.
+ * - [IMPLICIT_TYPES_BODY_RESOLVE] – The compiler can jump from one declaration to another during this phase as one
+ *   declaration with an implicit type can depend on an implicit type on another declaration,
+ *   and the compiler needs to calculate the type for it firstly.
+ *
+ * @see org.jetbrains.kotlin.fir.symbols.FirLazyResolveContractViolationException
+ */
 enum class FirResolvePhase(val noProcessor: Boolean = false) {
+    /**
+     * We ran the translator from some parser AST to FIR tree.
+     * Currently, FIR supports two parser representations:
+     * - Program Structure Interface ([PSI][com.intellij.psi.PsiElement])
+     * - Light Tree ([LT][com.intellij.lang.LighterASTNode])
+     *
+     * During conversion, the FIR translator performs desugaring of the source code.
+     * This includes replacing all `if` expressions with corresponding `when` expressions,
+     * converting `for` loops into blocks with `iterator` variable declaration and `while` loop, and similar.
+     */
     RAW_FIR(noProcessor = true),
+
+    /**
+     * The compiler resolves all imports in the file.
+     * Effectively, it means that the compiler splits all imports on longest existing package part and related class qualifier.
+     * More specifically, if an import is `import aaa.bbb.ccc.D` then the compiler tries to resolve `aaa.bbb.ccc` package firstly
+     * and if it is not found then trying to find `aaa.bbb` package.
+     */
     IMPORTS,
+
+    /**
+     * The compiler resolves types of some specific compiler annotations (like [SinceKotlin] or [JvmRecord])
+     * which are required earlier than [TYPES] phase or other annotations which are required for some compiler plugins.
+     * For some annotations (like [Deprecated] or [Target]) not only the type, but also the arguments are resolved.
+     *
+     * Also, calculates [DeprecationsProvider].
+     *
+     * This is a [*jumping phase*][FirResolvePhase].
+     */
     COMPILER_REQUIRED_ANNOTATIONS,
+
+    /**
+     * The compiler generates companion objects which were provided by compiler plugins.
+     */
     COMPANION_GENERATION,
+
+    /**
+     * The compiler resolves all supertypes of classes and performs type aliases expansion.
+     *
+     * This is a [*jumping phase*][FirResolvePhase].
+     */
     SUPER_TYPES,
+
+    /**
+     * The compiler collects and records all inheritors of sealed classes.
+     */
     SEALED_CLASS_INHERITORS,
+
+    /**
+     * The compiler resolves all other explicitly written types in declaration headers including
+     * - explicit return type for [callables][FirCallableDeclaration]
+     * - value parameters type for [functions][FirFunction]
+     * - property accessors type for [variables][FirVariable]
+     * - backing field type for [variables][FirVariable]
+     * - extension receivers type for [callables][FirCallableDeclaration]
+     * - context receivers type for [callables][FirCallableDeclaration] and [classes][FirRegularClass]
+     * - bounds types for [type parameters][FirTypeParameter]
+     * - types of annotations (without resolution of annotation arguments)
+     * for [annotation containers][org.jetbrains.kotlin.fir.FirAnnotationContainer].
+     *
+     * @see IMPLICIT_TYPES_BODY_RESOLVE
+     */
     TYPES,
+
+    /**
+     * The compiler resolves modality, visibility, and modifiers for [member declarations][FirMemberDeclaration].
+     * Note: member's modality and modifiers may depend on super declarations in the case when "this"
+     * member overrides some other member.
+     *
+     * This is a [*jumping phase*][FirResolvePhase].
+     */
     STATUS,
+
+    /**
+     * The compiler matches and records an `expect` member declaration for `actual` [member declarations][FirMemberDeclaration].
+     */
     EXPECT_ACTUAL_MATCHING,
+
+    /**
+     * The compiler resolves a [contract][org.jetbrains.kotlin.fir.contracts.FirContractDescription] definition in [contract owners][FirContractDescriptionOwner]:
+     * - [property accessors][FirPropertyAccessor]
+     * - [functions][FirSimpleFunction]
+     * - [constructors][FirConstructor]
+     */
     CONTRACTS,
+
+    /**
+     * The compiler resolves types for [callable declarations][FirCallableDeclaration] without an explicit return type.
+     * Examples:
+     * ```kotlin
+     * fun foo() = 0 // implicit type is Int
+     * val bar = "str" // implicit type is String
+     * val baz get() = foo() // implicit type is Int
+     * ```
+     *
+     * This is a [*jumping phase*][FirResolvePhase].
+     *
+     * @see TYPES
+     */
     IMPLICIT_TYPES_BODY_RESOLVE,
+
+    /**
+     * The compiler resolves arguments of annotations in declaration headers.
+     */
     ANNOTATION_ARGUMENTS,
+
+    /**
+     * The compiler resolves bodies of declarations including
+     * - bodies for [functions][FirFunction]
+     * - bodies for [anonymous initializers][FirAnonymousInitializer]
+     * - initializers for [variables][FirVariable]
+     * - delegates for [variables][FirVariable]
+     * - default values for [value parameters][FirValueParameter]
+     *
+     * Also, during this resolution,
+     * the compiler calculates [control flow graph][org.jetbrains.kotlin.fir.references.FirControlFlowGraphReference]
+     * for declaration which [own][FirControlFlowGraphOwner] it.
+     */
     BODY_RESOLVE;
 
     val next: FirResolvePhase get() = values()[ordinal + 1]

docs/fir/fir-basics.md

@@ -7,32 +7,25 @@ FIR (Frontend IR) compiler is a new Kotlin Frontend that has entirely new archit
 
 FIR tree is a core abstraction for the new frontend. FIR tree contains all information the compiler knows about the code. Compilation in the
 FIR compiler is performed in separate compiler phases. Compiler phases are executed sequentially in the CLI compiler and lazily in the Analysis API.
-There is a guarantee that if we have two phases: `A` and `B` where `B` follows `A`, then all FIR elements visible in phase `B are` are already resolved to phase `A`. This is a very important invariant that determines which information in FIR elements is resolved on each
+There is a guarantee that if we have two phases: `A` and `B` where `B` follows `A`, then all FIR elements visible in phase `B` are already resolved to phase `A`. 
-phase.
+This is a crucial invariant that determines which information in FIR elements is resolved in each phase.
+See [FirResolvePhase](../../compiler/fir/tree/src/org/jetbrains/kotlin/fir/declarations/FirResolvePhase.kt) for more details and up-to-date information regarding the compiler phases.
 
 ## Phases
-List of all FIR phases which exists in the compiler right now:
+List of all FIR phases that exist in the compiler right now with a short description:
-- **RAW_FIR**: In this phase, we ran the translator from some parser AST to FIR tree. Currently, FIR supports two parser representations: PSI and LighterAst.
+- **RAW_FIR**: We ran the translator from some parser AST to FIR tree.
-  During conversion, the FIR translator performs desugaring of the source code. This includes replacing all `if` expressions with
+- **IMPORTS**: The compiler splits all imports on longest existing package part and related class qualifier.
-  corresponding `when` expressions, converting `for` loops into blocks with `iterator` variable declaration and `while` loop, and similar.
+- **COMPILER_REQUIRED_ANNOTATIONS**: The compiler resolves types of some specific compiler annotations which are required earlier than the **TYPES** phase.
-- **IMPORTS**: In this stage, the compiler resolves qualifiers of all imports, excluding the last part of an imported name. More specifically, if an import
+- **COMPANION_GENERATION**. The compiler generates companion objects which were provided by compiler plugins
-  is `import aaa.bbb.ccc.D` then the compiler tries to resolve `aaa.bbb.ccc` package.
+- **SUPER_TYPES**: The compiler resolves all supertypes of classes and performs type aliases expansion. 
-- **ANNOTATIONS_FOR_PLUGINS** and **COMPANION_GENERATION**. Those phases are required for plugin support
+- **SEALED_CLASS_INHERITORS**: The compiler collects and records all inheritors of sealed classes.
-- **SUPER_TYPES**: At this stage, the compiler resolves all supertypes of all non-local classes and performs type aliases expansion. 
+- **TYPES**: The compiler resolves all other explicitly written types in declaration headers.
-- **SEALED_CLASS_INHERITORS**: At this stage, the compiler collects and records all inheritors of non-local sealed classes.
+- **STATUS**: The compiler resolves modality, visibility, and modifiers for member declarations.
-- **TYPES**: At this stage, the compiler resolves all other explicitly written types in declaration headers, including:
+- **EXPECT_ACTUAL_MATCHING**: The compiler matches and records an `expect` member declaration for `actual` member declarations.
-    - explicit return types of members
+- **CONTRACTS**: The compiler resolves a contract definition in property accessors, functions, and constructors.
-    - types of value parameters of functions
+- **IMPLICIT_TYPES_BODY_RESOLVE**: The compiler resolves types for callable declarations without an explicit return type.
-    - extension receivers of members
+- **ANNOTATION_ARGUMENTS**: The compiler resolves arguments of annotations in declaration headers.
-    - bounds of type parameters
+- **BODY_RESOLVE**: The compiler resolves bodies for declarations.
-    - types of annotations (without resolution of annotation arguments)
-- **STATUS**: At this phase, the compiler resolves modality, visibility, and modifiers of all non-local declarations. Note that members modality and
-  modifiers may depend on super declarations in the case when "this" member overrides some other member.
-- **ARGUMENTS_OF_ANNOTATIONS**:  At this phase, the compiler resolves arguments of annotations in declaration headers.
-- **CONTRACTS**: At this phase, the compiler resolves a contract block in property accessors and functions.
-- **IMPLICIT_TYPES_BODY_RESOLVE**: At this stage, the compiler resolves bodies of all functions and properties which have no explicit return
-  type (`fun foo() = ...`)
-- **BODY_RESOLVE**: At this stage, all other bodies are resolved.
 - **CHECKERS**: At this point, all FIR tree is already resolved, and it's time to check it and report diagnostics for the user.
   Note that it's allowed to report diagnostics only in this phase. If some diagnostic can be detected only during resolution (e.g, error
   that type of argument does not match with the expected type of parameter) then information about such errors is saved right inside the FIR tree
@@ -40,8 +33,9 @@ List of all FIR phases which exists in the compiler right now:
 
 - **FIR2IR**: At this stage, the compiler transforms resolved FIR to backed IR.
 
-As you may notice, phases from `SUPER_TYPES` till `CONTRACTS` run for non-local declarations. When the compiler meets some local
+As you may notice, phases from `COMPILER_REQUIRED_ANNOTATIONS` till `ANNOTATION_ARGUMENTS` run for non-local declarations.
-classifier declaration (local class or anonymous object) during body resolve, it runs all those phases for that classifier specifically.
+When the compiler meets some local classifier declaration (local class or anonymous object) during body resolve,
+it runs all those phases for that classifier specifically.
 
 ## FIR elements