[IR] Add kdocs for IrSymbol-related classes and interfaces
This commit is contained in:
Sergej Jaskiewicz
committed by
Space Team
Space Team
parent
e473eaa5d6
commit
5f5b32b8ae
@@ -10,6 +10,22 @@ import org.jetbrains.kotlin.ir.ObsoleteDescriptorBasedAPI
|
||||
import org.jetbrains.kotlin.ir.declarations.*
|
||||
import org.jetbrains.kotlin.ir.util.IdSignature
|
||||
|
||||
/**
|
||||
* Used to handle `expect` declarations.
|
||||
*
|
||||
* Before actualization, [delegate] refers to the symbol of the `expect` declaration. After actualization,
|
||||
* [delegate] is replaced with the symbol of the corresponding `actual` declaration.
|
||||
*
|
||||
* A delegating symbol behaves exactly the same as its [delegate].
|
||||
*
|
||||
* [About `expect` and `actual` declarations.](https://kotlinlang.org/docs/multiplatform-connect-to-apis.html)
|
||||
*
|
||||
* @property delegate Before actualization — the symbol of the `expect` declaration,
|
||||
* after actualization — the symbol of the corresponding `actual` declaration.
|
||||
*
|
||||
* @see org.jetbrains.kotlin.backend.common.serialization.KotlinIrLinker.handleExpectActualMapping
|
||||
* @see org.jetbrains.kotlin.backend.common.serialization.KotlinIrLinker.finalizeExpectActual
|
||||
*/
|
||||
abstract class IrDelegatingSymbol<DelegateSymbol, Owner, Descriptor>(var delegate: DelegateSymbol) : IrBindableSymbol<Descriptor, Owner>
|
||||
where DelegateSymbol : IrBindableSymbol<Descriptor, Owner>,
|
||||
Owner : IrSymbolOwner,
|
||||
|
||||
@@ -19,67 +19,200 @@ package org.jetbrains.kotlin.ir.symbols
|
||||
import org.jetbrains.kotlin.descriptors.*
|
||||
import org.jetbrains.kotlin.ir.ObsoleteDescriptorBasedAPI
|
||||
import org.jetbrains.kotlin.ir.declarations.*
|
||||
import org.jetbrains.kotlin.ir.expressions.IrReturnableBlock
|
||||
import org.jetbrains.kotlin.ir.descriptors.IrBasedDeclarationDescriptor
|
||||
import org.jetbrains.kotlin.ir.expressions.*
|
||||
import org.jetbrains.kotlin.ir.types.IrSimpleType
|
||||
import org.jetbrains.kotlin.ir.types.IrTypeAbbreviation
|
||||
import org.jetbrains.kotlin.ir.util.IdSignature
|
||||
import org.jetbrains.kotlin.ir.util.SymbolTable
|
||||
import org.jetbrains.kotlin.types.model.TypeConstructorMarker
|
||||
import org.jetbrains.kotlin.types.model.TypeParameterMarker
|
||||
|
||||
/**
|
||||
* A special object that can be used to refer to [IrDeclaration]s and some other entities from IR nodes.
|
||||
*
|
||||
* For example, [IrCall] uses [IrSimpleFunctionSymbol] to refer to the [IrSimpleFunction] that is being called.
|
||||
*
|
||||
* **Q:** Why not just use the [IrSimpleFunction] class itself?
|
||||
*
|
||||
* **A:** Because a symbol, unlike a declaration, can be bound or unbound (see [isBound]).
|
||||
*
|
||||
* We need this distinction to work with IR before the linkage phase. In pre-linkage IR the symbols referencing declarations from
|
||||
* other modules are not yet bound.
|
||||
*
|
||||
* During the linkage phase, we collect all the unbound symbols in the IR tree and try to resolve them to the declarations they should
|
||||
* refer to. For unbound symbols for public declarations from other modules, [signature] is used to resolve those declarations.
|
||||
*
|
||||
* @see IdSignature
|
||||
* @see SymbolTable
|
||||
*/
|
||||
interface IrSymbol {
|
||||
|
||||
/**
|
||||
* The declaration that this symbol refers to if it's bound.
|
||||
*
|
||||
* If the symbol is unbound, throws [IllegalStateException].
|
||||
*
|
||||
* **Q:** Why we didn't make this property nullable instead of throwing an exception?
|
||||
*
|
||||
* **A:** Because we most often need to access a symbol's owner in lowerings, which happen after linkage, at which point all symbols
|
||||
* should be already bound. Declaring this property nullable would make working with it more difficult most of the time.
|
||||
*/
|
||||
val owner: IrSymbolOwner
|
||||
|
||||
/**
|
||||
* If [hasDescriptor] is `true`, returns the [DeclarationDescriptor] of the declaration that this symbol was created for.
|
||||
* Otherwise, returns a dummy [IrBasedDeclarationDescriptor] that serves as a descriptor-like view to [owner].
|
||||
*/
|
||||
@ObsoleteDescriptorBasedAPI
|
||||
val descriptor: DeclarationDescriptor
|
||||
|
||||
/**
|
||||
* Returns `true` if this symbol was created from a [DeclarationDescriptor] either emitted by the K1 (aka classic) frontend,
|
||||
* or from deserialized metadata.
|
||||
*
|
||||
* @see descriptor
|
||||
*/
|
||||
@ObsoleteDescriptorBasedAPI
|
||||
val hasDescriptor: Boolean
|
||||
|
||||
/**
|
||||
* Whether this symbol has already been resolved to its [owner].
|
||||
*/
|
||||
val isBound: Boolean
|
||||
|
||||
/**
|
||||
* If this symbol refers to a publicly accessible declaration (from the binary artifact point of view),
|
||||
* returns the binary signature of that declaration.
|
||||
*
|
||||
* Otherwise, returns `null`.
|
||||
*
|
||||
* @see IdSignature.isPubliclyVisible
|
||||
*/
|
||||
val signature: IdSignature?
|
||||
|
||||
// TODO: remove once JS IR IC migrates to a different stable tag generation scheme
|
||||
// Used to store signatures in private symbols for JS IC
|
||||
/**
|
||||
* If this symbol refers to a local declaration, the signature of that declaration, otherwise `null`.
|
||||
*
|
||||
* @see IdSignature.isPubliclyVisible
|
||||
*/
|
||||
var privateSignature: IdSignature?
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether this symbol refers to a publicly accessible declaration (from the binary artifact point of view).
|
||||
*
|
||||
* The symbol doesn't have to be bound.
|
||||
*/
|
||||
val IrSymbol.isPublicApi: Boolean
|
||||
get() = signature != null
|
||||
|
||||
/**
|
||||
* A stricter-typed [IrSymbol] that allows to set the owner using the [bind] method. The owner can be set only once.
|
||||
*
|
||||
* In fact, any [IrSymbol] is [IrBindableSymbol], but having a non-generic interface like [IrSymbol] is sometimes useful.
|
||||
*
|
||||
* Only leaf interfaces in the symbol hierarchy inherit from this interface.
|
||||
*/
|
||||
interface IrBindableSymbol<out Descriptor : DeclarationDescriptor, Owner : IrSymbolOwner> : IrSymbol {
|
||||
override val owner: Owner
|
||||
|
||||
@ObsoleteDescriptorBasedAPI
|
||||
override val descriptor: Descriptor
|
||||
|
||||
/**
|
||||
* Sets this symbol's owner.
|
||||
*
|
||||
* Throws [IllegalStateException] if this symbol has already been bound.
|
||||
*/
|
||||
fun bind(owner: Owner)
|
||||
}
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is either [IrFile] or [IrExternalPackageFragment].
|
||||
*/
|
||||
sealed interface IrPackageFragmentSymbol : IrSymbol {
|
||||
@ObsoleteDescriptorBasedAPI
|
||||
override val descriptor: PackageFragmentDescriptor
|
||||
}
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrFile]. Such a symbol is always module-private.
|
||||
*
|
||||
* [IrFileSymbol] is never actually serialized, but is useful for deserializing private top-level declarations.
|
||||
*
|
||||
* @see IdSignature.FileSignature
|
||||
*/
|
||||
interface IrFileSymbol : IrPackageFragmentSymbol, IrBindableSymbol<PackageFragmentDescriptor, IrFile>
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrExternalPackageFragment].
|
||||
*/
|
||||
interface IrExternalPackageFragmentSymbol : IrPackageFragmentSymbol, IrBindableSymbol<PackageFragmentDescriptor, IrExternalPackageFragment>
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrAnonymousInitializer].
|
||||
*
|
||||
* It's not very useful on its own, but since [IrAnonymousInitializer] is an [IrDeclaration], and [IrDeclaration]s must have symbols,
|
||||
* here we are.
|
||||
*
|
||||
* This symbol is never public (wrt linkage).
|
||||
*/
|
||||
interface IrAnonymousInitializerSymbol : IrBindableSymbol<ClassDescriptor, IrAnonymousInitializer>
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrEnumEntry].
|
||||
*
|
||||
* @see IrGetEnumValue
|
||||
*/
|
||||
interface IrEnumEntrySymbol : IrBindableSymbol<ClassDescriptor, IrEnumEntry>
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrField].
|
||||
*
|
||||
* @see IrGetField
|
||||
* @see IrSetField
|
||||
*/
|
||||
interface IrFieldSymbol : IrBindableSymbol<PropertyDescriptor, IrField>
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrClass], [IrScript] or [IrTypeParameter].
|
||||
*
|
||||
* @see IrSimpleType
|
||||
* @see IrClassReference
|
||||
*/
|
||||
sealed interface IrClassifierSymbol : IrSymbol, TypeConstructorMarker {
|
||||
@ObsoleteDescriptorBasedAPI
|
||||
override val descriptor: ClassifierDescriptor
|
||||
}
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrClass].
|
||||
*
|
||||
* @see IrClass.sealedSubclasses
|
||||
* @see IrCall.superQualifierSymbol
|
||||
* @see IrFieldAccessExpression.superQualifierSymbol
|
||||
*/
|
||||
interface IrClassSymbol : IrClassifierSymbol, IrBindableSymbol<ClassDescriptor, IrClass>
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrScript].
|
||||
*/
|
||||
interface IrScriptSymbol : IrClassifierSymbol, IrBindableSymbol<ScriptDescriptor, IrScript>
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrTypeParameter].
|
||||
*/
|
||||
interface IrTypeParameterSymbol : IrClassifierSymbol, IrBindableSymbol<TypeParameterDescriptor, IrTypeParameter>, TypeParameterMarker
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrValueParameter] or [IrVariable].
|
||||
*
|
||||
* @see IrGetValue
|
||||
* @see IrSetValue
|
||||
*/
|
||||
sealed interface IrValueSymbol : IrSymbol {
|
||||
@ObsoleteDescriptorBasedAPI
|
||||
override val descriptor: ValueDescriptor
|
||||
@@ -87,10 +220,21 @@ sealed interface IrValueSymbol : IrSymbol {
|
||||
override val owner: IrValueDeclaration
|
||||
}
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrValueParameter].
|
||||
*/
|
||||
interface IrValueParameterSymbol : IrValueSymbol, IrBindableSymbol<ParameterDescriptor, IrValueParameter>
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrVariable].
|
||||
*/
|
||||
interface IrVariableSymbol : IrValueSymbol, IrBindableSymbol<VariableDescriptor, IrVariable>
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrFunction] or [IrReturnableBlock].
|
||||
*
|
||||
* @see IrReturn
|
||||
*/
|
||||
sealed interface IrReturnTargetSymbol : IrSymbol {
|
||||
@ObsoleteDescriptorBasedAPI
|
||||
override val descriptor: FunctionDescriptor
|
||||
@@ -98,18 +242,47 @@ sealed interface IrReturnTargetSymbol : IrSymbol {
|
||||
override val owner: IrReturnTarget
|
||||
}
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrConstructor] or [IrSimpleFunction].
|
||||
*
|
||||
* @see IrFunctionReference
|
||||
*/
|
||||
sealed interface IrFunctionSymbol : IrReturnTargetSymbol {
|
||||
override val owner: IrFunction
|
||||
}
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrConstructor].
|
||||
*
|
||||
* @see IrConstructorCall
|
||||
*/
|
||||
interface IrConstructorSymbol : IrFunctionSymbol, IrBindableSymbol<ClassConstructorDescriptor, IrConstructor>
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrSimpleFunction].
|
||||
*
|
||||
* @see IrCall
|
||||
*/
|
||||
interface IrSimpleFunctionSymbol : IrFunctionSymbol, IrBindableSymbol<FunctionDescriptor, IrSimpleFunction>
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrReturnableBlock].
|
||||
*/
|
||||
interface IrReturnableBlockSymbol : IrReturnTargetSymbol, IrBindableSymbol<FunctionDescriptor, IrReturnableBlock>
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrProperty].
|
||||
*/
|
||||
interface IrPropertySymbol : IrBindableSymbol<PropertyDescriptor, IrProperty>
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrLocalDelegatedProperty].
|
||||
*/
|
||||
interface IrLocalDelegatedPropertySymbol : IrBindableSymbol<VariableDescriptorWithAccessors, IrLocalDelegatedProperty>
|
||||
|
||||
/**
|
||||
* A symbol whose [owner] is [IrTypeAlias].
|
||||
*
|
||||
* @see IrTypeAbbreviation
|
||||
*/
|
||||
interface IrTypeAliasSymbol : IrBindableSymbol<TypeAliasDescriptor, IrTypeAlias>
|
||||
|
||||
@@ -14,6 +14,13 @@ import org.jetbrains.kotlin.ir.symbols.*
|
||||
import org.jetbrains.kotlin.ir.util.IdSignature
|
||||
import org.jetbrains.kotlin.ir.util.render
|
||||
|
||||
/**
|
||||
* The base class for all non-public (wrt linkage) symbols.
|
||||
*
|
||||
* Its [signature] is always `null`.
|
||||
*
|
||||
* TODO: Merge with [IrPublicSymbolBase] ([KT-44721](https://youtrack.jetbrains.com/issue/KT-44721))
|
||||
*/
|
||||
@OptIn(ObsoleteDescriptorBasedAPI::class)
|
||||
abstract class IrSymbolBase<out Descriptor : DeclarationDescriptor>(
|
||||
private val _descriptor: Descriptor?
|
||||
|
||||
@@ -13,6 +13,13 @@ import org.jetbrains.kotlin.ir.symbols.*
|
||||
import org.jetbrains.kotlin.ir.util.IdSignature
|
||||
import org.jetbrains.kotlin.ir.util.render
|
||||
|
||||
/**
|
||||
* The base class for all public (wrt linkage) symbols.
|
||||
*
|
||||
* Its [signature] is never `null`.
|
||||
*
|
||||
* TODO: Merge with [IrSymbolBase] ([KT-44721](https://youtrack.jetbrains.com/issue/KT-44721))
|
||||
*/
|
||||
abstract class IrPublicSymbolBase<out Descriptor : DeclarationDescriptor>(
|
||||
override val signature: IdSignature,
|
||||
private val _descriptor: Descriptor?
|
||||
|
||||
Reference in New Issue
Block a user