[FIR] Proofread/edit new KDoc for FirResolvePhase
This commit is contained in:
Marco Pennekamp
committed by
Space Team
Space Team
parent
55159694df
commit
fd66e5d5b8
@@ -9,72 +9,81 @@ 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 CLI compiler mode (aka full resolution mode): the compiler executes all phases sequentially for all declarations.
|
||||
* This means that the processor for phase `A` will transform all declarations in the first round.
|
||||
* In the next round, the processor for phase `B` (which follows `A`) 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).
|
||||
* (on demand) for some particular declaration (not for all declarations in contrast 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].
|
||||
* ### Contracts
|
||||
*
|
||||
* 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.
|
||||
* There are a few contracts for both modes:
|
||||
*
|
||||
* 1. All phases **must be executed only in a sequential manner**.
|
||||
* For example, if the compiler wants to resolve some declaration to the phase [COMPILER_REQUIRED_ANNOTATIONS],
|
||||
* then it has to resolve it to all previous phases first: to the [RAW_FIR] phase,
|
||||
* then to the [IMPORTS] phase, and only afterward can the compiler execute the phase [COMPILER_REQUIRED_ANNOTATIONS].
|
||||
*
|
||||
* 2. The compiler **must not request and cannot rely on any information from the higher phases**.
|
||||
* For example, during the [STATUS] phase, we cannot access information regarding implicit types
|
||||
* as they will only be calculated during the [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)
|
||||
* we cannot request type information for other declarations (except information from the [SUPER_TYPES] phase, such as 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.
|
||||
*
|
||||
* A *jumping phase* is a phase that can request the phase-specific information during that 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
|
||||
*
|
||||
* - [COMPILER_REQUIRED_ANNOTATIONS] – The compiler can jump from the use site 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.
|
||||
* - [STATUS] – The compiler resolves the status for super declarations first.
|
||||
* - [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.
|
||||
* declaration with an implicit type can depend on the implicit type of another declaration,
|
||||
* and the compiler needs to calculate the type for it first.
|
||||
*
|
||||
* @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.
|
||||
* converting `for` loops into blocks with an `iterator` variable declaration and a `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.
|
||||
*
|
||||
* Effectively, this means that the compiler splits all imports on the longest existing package part and the related class qualifier.
|
||||
* More specifically, if an import is `import aaa.bbb.ccc.D`, the compiler tries to resolve the package `aaa.bbb.ccc` first.
|
||||
* If it doesn't exist, it tries to find the package `aaa.bbb`, and so on. The result is a pair of package name and class qualifier
|
||||
* which exactly identifies the imported declaration.
|
||||
*/
|
||||
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.
|
||||
* which are required earlier than the [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].
|
||||
* Also calculates [DeprecationsProvider].
|
||||
*
|
||||
* This is a [*jumping phase*][FirResolvePhase].
|
||||
*/
|
||||
@@ -86,7 +95,7 @@ enum class FirResolvePhase(val noProcessor: Boolean = false) {
|
||||
COMPANION_GENERATION,
|
||||
|
||||
/**
|
||||
* The compiler resolves all supertypes of classes and performs type aliases expansion.
|
||||
* The compiler resolves all supertypes of classes and performs type alias expansion.
|
||||
*
|
||||
* This is a [*jumping phase*][FirResolvePhase].
|
||||
*/
|
||||
@@ -98,16 +107,17 @@ enum class FirResolvePhase(val noProcessor: Boolean = false) {
|
||||
SEALED_CLASS_INHERITORS,
|
||||
|
||||
/**
|
||||
* The compiler resolves all other explicitly written types in declaration headers including
|
||||
* 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]
|
||||
* - value parameter types for [functions][FirFunction]
|
||||
* - property accessor types 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]
|
||||
* - extension receiver type for [callables][FirCallableDeclaration]
|
||||
* - context receiver types for [callables][FirCallableDeclaration] and [classes][FirRegularClass]
|
||||
* - type bounds for [type parameters][FirTypeParameter]
|
||||
* - types of annotations (without resolution of annotation arguments)
|
||||
* for [annotation containers][org.jetbrains.kotlin.fir.FirAnnotationContainer].
|
||||
* for [annotation containers][org.jetbrains.kotlin.fir.FirAnnotationContainer].
|
||||
*
|
||||
* @see IMPLICIT_TYPES_BODY_RESOLVE
|
||||
*/
|
||||
@@ -115,20 +125,21 @@ enum class FirResolvePhase(val noProcessor: Boolean = false) {
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* Note: A member's modality and its modifiers may depend on super declarations 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].
|
||||
* The compiler matches and records an `expect` member declaration for each `actual` [member declaration][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]
|
||||
@@ -137,7 +148,9 @@ enum class FirResolvePhase(val noProcessor: Boolean = false) {
|
||||
|
||||
/**
|
||||
* 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
|
||||
@@ -156,7 +169,8 @@ enum class FirResolvePhase(val noProcessor: Boolean = false) {
|
||||
ANNOTATION_ARGUMENTS,
|
||||
|
||||
/**
|
||||
* The compiler resolves bodies of declarations including
|
||||
* The compiler resolves bodies of declarations, including:
|
||||
*
|
||||
* - bodies for [functions][FirFunction]
|
||||
* - bodies for [anonymous initializers][FirAnonymousInitializer]
|
||||
* - initializers for [variables][FirVariable]
|
||||
@@ -164,8 +178,8 @@ enum class FirResolvePhase(val noProcessor: Boolean = false) {
|
||||
* - 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.
|
||||
* the compiler calculates the [control flow graph][org.jetbrains.kotlin.fir.references.FirControlFlowGraphReference]
|
||||
* for its [owner][FirControlFlowGraphOwner] declaration.
|
||||
*/
|
||||
BODY_RESOLVE;
|
||||
|
||||
|
||||
Reference in New Issue
Block a user