From fd66e5d5b8cb7c27a0711bcc333e0976b7feeb08 Mon Sep 17 00:00:00 2001 From: Marco Pennekamp Date: Fri, 16 Feb 2024 22:35:47 +0100 Subject: [PATCH] [FIR] Proofread/edit new KDoc for `FirResolvePhase` --- .../fir/declarations/FirResolvePhase.kt | 94 +++++++++++-------- 1 file changed, 54 insertions(+), 40 deletions(-) diff --git a/compiler/fir/tree/src/org/jetbrains/kotlin/fir/declarations/FirResolvePhase.kt b/compiler/fir/tree/src/org/jetbrains/kotlin/fir/declarations/FirResolvePhase.kt index 8fd4d35f670..fd1818dfe48 100644 --- a/compiler/fir/tree/src/org/jetbrains/kotlin/fir/declarations/FirResolvePhase.kt +++ b/compiler/fir/tree/src/org/jetbrains/kotlin/fir/declarations/FirResolvePhase.kt @@ -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;