Analysis API: add KDoc, small cosmetic improvements

2021-11-30 16:15:51 +01:00
parent 6e4c87f138
commit dc9c2aa39d
15 changed files with 173 additions and 50 deletions
@@ -299,9 +299,9 @@ internal fun ConstantValue<*>.toKtAnnotationValue(): KtAnnotationValue {
        is KClassValue -> when (val value = value) {
            is KClassValue.Value.LocalClass -> {
                val descriptor = value.type.constructor.declarationDescriptor as ClassDescriptor
-                KtLocalKClassAnnotationValue(descriptor.source.getPsi() as KtClassOrObject, sourcePsi = null)
+                KtKClassAnnotationValue.KtLocalKClassAnnotationValue(descriptor.source.getPsi() as KtClassOrObject, sourcePsi = null)
            }
-            is KClassValue.Value.NormalClass -> KtNonLocalKClassAnnotationValue(value.classId, sourcePsi = null)
+            is KClassValue.Value.NormalClass -> KtKClassAnnotationValue.KtNonLocalKClassAnnotationValue(value.classId, sourcePsi = null)
        }

        is AnnotationValue -> {
@@ -461,5 +461,5 @@ internal fun AnnotationDescriptor.toKtAnnotationApplication(): KtAnnotationAppli

 internal fun AnnotationDescriptor.getKtNamedAnnotationArguments() =
    allValueArguments.map { (name, value) ->
-        KtNamedAnnotationValue(name.asString(), value.toKtAnnotationValue())
+        KtNamedAnnotationValue(name, value.toKtAnnotationValue())
    }
@@ -109,7 +109,8 @@ internal class KtFe10TypeRenderer(private val options: KtTypeRendererOptions, pr
        }

        printCollection(namedValues, separator = ", ", prefix = "(", postfix = ")") { (name, value) ->
-            append(name).append(" = ")
+            append(name.render())
+            append(" = ")
            renderConstantValueDebug(value)
        }
    }
@@ -122,7 +123,7 @@ internal class KtFe10TypeRenderer(private val options: KtTypeRendererOptions, pr
            is KtEnumEntryAnnotationValue -> append(value.callableId?.asSingleFqName()?.render())
            is KtConstantAnnotationValue -> append(value.constantValue.constantValueKind.asString).append("(").append(value.constantValue.value.toString()).append(")")
            KtUnsupportedAnnotationValue -> append(KtUnsupportedAnnotationValue::class.java.simpleName)
-            is KtKClassAnnotationValue -> append(value.render())
+            is KtKClassAnnotationValue -> append(value.renderAsSourceCode())
        }
    }

@@ -5,8 +5,8 @@

 package org.jetbrains.kotlin.analysis.api.descriptors.utils

+import org.jetbrains.kotlin.analysis.api.annotations.renderAsSourceCode
 import org.jetbrains.kotlin.analysis.api.descriptors.symbols.descriptorBased.base.classId
-import org.jetbrains.kotlin.analysis.api.annotations.KtAnnotationValueRenderer
 import org.jetbrains.kotlin.analysis.api.descriptors.symbols.descriptorBased.base.toKtAnnotationValue
 import org.jetbrains.kotlin.analysis.utils.printer.PrettyPrinter
 import org.jetbrains.kotlin.builtins.StandardNames
@@ -39,7 +39,7 @@ internal fun PrettyPrinter.renderFe10Annotations(
            printCollectionIfNotEmpty(valueArguments, separator = ", ", prefix = "(", postfix = ")") { (name, value) ->
                append(name.render())
                append(" = ")
-                append(KtAnnotationValueRenderer.render(value.toKtAnnotationValue()))
+                append(value.toKtAnnotationValue().renderAsSourceCode())
            }

            append(separator)
@@ -16,21 +16,22 @@ import org.jetbrains.kotlin.fir.types.ConeClassLikeType
 import org.jetbrains.kotlin.fir.types.classId
 import org.jetbrains.kotlin.fir.types.coneType
 import org.jetbrains.kotlin.name.ClassId
+import org.jetbrains.kotlin.name.Name

-internal fun mapAnnotationParameters(annotation: FirAnnotation, session: FirSession): Map<String, FirExpression> {
-    if (annotation.resolved) return annotation.argumentMapping.mapping.mapKeys { (name, _) -> name.identifier }
+internal fun mapAnnotationParameters(annotation: FirAnnotation, session: FirSession): Map<Name, FirExpression> {
+    if (annotation.resolved) return annotation.argumentMapping.mapping.mapKeys { (name, _) -> name }
    if (annotation !is FirAnnotationCall) return emptyMap()
    val annotationCone = annotation.annotationTypeRef.coneType as? ConeClassLikeType ?: return emptyMap()

    val annotationPrimaryCtor = (annotationCone.lookupTag.toSymbol(session)?.fir as? FirRegularClass)?.primaryConstructorIfAny(session)?.fir
    val annotationCtorParameterNames = annotationPrimaryCtor?.valueParameters?.map { it.name }

-    val resultMap = mutableMapOf<String, FirExpression>()
+    val resultMap = mutableMapOf<Name, FirExpression>()

    val namesSequence = annotationCtorParameterNames?.asSequence()?.iterator()

    for (argument in annotation.argumentList.arguments.filterIsInstance<FirNamedArgumentExpression>()) {
-        resultMap[argument.name.asString()] = argument.expression
+        resultMap[argument.name] = argument.expression
    }

    if (namesSequence != null) {
@@ -38,7 +39,7 @@ internal fun mapAnnotationParameters(annotation: FirAnnotation, session: FirSess
            if (argument is FirNamedArgumentExpression) continue

            while (namesSequence.hasNext()) {
-                val name = namesSequence.next().asString()
+                val name = namesSequence.next()
                if (!resultMap.contains(name)) {
                    resultMap[name] = argument
                    break
@@ -17,13 +17,14 @@ import org.jetbrains.kotlin.fir.references.FirResolvedNamedReference
 import org.jetbrains.kotlin.fir.symbols.impl.FirConstructorSymbol
 import org.jetbrains.kotlin.fir.symbols.impl.FirEnumEntrySymbol
 import org.jetbrains.kotlin.fir.symbols.impl.FirNamedFunctionSymbol
+import org.jetbrains.kotlin.name.Name
 import org.jetbrains.kotlin.psi.*
 import org.jetbrains.kotlin.psi.psiUtil.parents
 import org.jetbrains.kotlin.resolve.ArrayFqNames

 internal object FirAnnotationValueConverter {
    fun toNamedConstantValue(
-        argumentMapping: Map<String, FirExpression>,
+        argumentMapping: Map<Name, FirExpression>,
        session: FirSession,
    ): List<KtNamedAnnotationValue> =
        argumentMapping.map { (name, expression) ->
@@ -100,9 +101,9 @@ internal object FirAnnotationValueConverter {
                    is FirConstructorSymbol -> {
                        val classSymbol = resolvedSymbol.getContainingClassSymbol(session) ?: return null
                        if ((classSymbol.fir as? FirClass)?.classKind == ClassKind.ANNOTATION_CLASS) {
-                            val resultMap = mutableMapOf<String, FirExpression>()
+                            val resultMap = mutableMapOf<Name, FirExpression>()
                            argumentMapping?.entries?.forEach { (arg, param) ->
-                                resultMap[param.name.asString()] = arg
+                                resultMap[param.name] = arg
                            }
                            KtAnnotationApplicationValue(
                                KtAnnotationApplication(
@@ -135,9 +136,12 @@ internal object FirAnnotationValueConverter {
            is FirGetClassCall -> {
                val symbol = (argument as FirResolvedQualifier).symbol
                when {
-                    symbol == null -> KtErrorClassAnnotationValue(sourcePsi)
-                    symbol.classId.isLocal -> KtLocalKClassAnnotationValue(symbol.fir.psi as KtClassOrObject, sourcePsi)
-                    else -> KtNonLocalKClassAnnotationValue(symbol.classId, sourcePsi)
+                    symbol == null -> KtKClassAnnotationValue.KtErrorClassAnnotationValue(sourcePsi)
+                    symbol.classId.isLocal -> KtKClassAnnotationValue.KtLocalKClassAnnotationValue(
+                        symbol.fir.psi as KtClassOrObject,
+                        sourcePsi
+                    )
+                    else -> KtKClassAnnotationValue.KtNonLocalKClassAnnotationValue(symbol.classId, sourcePsi)
                }
            }
            else -> null
@@ -8,9 +8,8 @@ package org.jetbrains.kotlin.analysis.api.fir.renderer
 import org.jetbrains.kotlin.analysis.api.fir.annotations.mapAnnotationParameters
 import org.jetbrains.kotlin.analysis.api.fir.evaluate.FirCompileTimeConstantEvaluator
 import org.jetbrains.kotlin.analysis.api.fir.evaluate.FirAnnotationValueConverter
-import org.jetbrains.kotlin.analysis.api.annotations.KtAnnotationValueRenderer
 import org.jetbrains.kotlin.analysis.api.annotations.KtUnsupportedAnnotationValue
-import org.jetbrains.kotlin.analysis.utils.printer.PrettyPrinter
+import org.jetbrains.kotlin.analysis.api.annotations.renderAsSourceCode
 import org.jetbrains.kotlin.builtins.StandardNames
 import org.jetbrains.kotlin.fir.FirSession
 import org.jetbrains.kotlin.fir.declarations.toAnnotationClassId
@@ -65,5 +64,5 @@ private fun renderConstant(value: FirExpression, useSiteSession: FirSession): St
    val constantValue = FirAnnotationValueConverter.toConstantValue(evaluated ?: value, useSiteSession)
        ?: KtUnsupportedAnnotationValue

-    return KtAnnotationValueRenderer.render(constantValue)
+    return constantValue.renderAsSourceCode()
 }
@@ -5,19 +5,34 @@

 package org.jetbrains.kotlin.analysis.api

-import org.jetbrains.kotlin.analysis.api.annotations.KtAnnotationValue
 import org.jetbrains.kotlin.analysis.api.base.KtConstantValue
 import org.jetbrains.kotlin.psi.KtExpression

+/**
+ * Value representing some property or variable initializer
+ */
 public sealed class KtInitializerValue {
+    /**
+     * [com.intellij.psi.PsiElement] of initializer. May be null if property/variable came from non-source file.
+     */
    public abstract val initializerPsi: KtExpression?
 }

+/**
+ * Initializer value which can be evaluated to constant. E.g, string value, number, null literal.
+ *
+ * For more info about constant values please see [official Kotlin documentation](https://kotlinlang.org/docs/properties.html#compile-time-constants]).
+ */
 public class KtConstantInitializerValue(
    public val constant: KtConstantValue,
    override val initializerPsi: KtExpression?
 ) : KtInitializerValue()

+/**
+ * Property intialzer which cannot be represented as Kotlin const value.
+ *
+ * See [KtConstantInitializerValue] for more info.
+ */
 public class KtNonConstantInitializerValue(
    override val initializerPsi: KtExpression?
 ) : KtInitializerValue()
@@ -10,9 +10,36 @@ import org.jetbrains.kotlin.name.ClassId
 import org.jetbrains.kotlin.psi.KtAnnotationEntry
 import org.jetbrains.kotlin.psi.KtCallElement

-public class KtAnnotationApplication(
+/**
+ * Application of annotation to some declaration, type, or as argument inside other annotation.
+ *
+ * Some examples:
+ * - For declarations: `@Deprecated("Should not be used") fun foo(){}`
+ * - For types: `fun foo(x: List<@A Int>){}`
+ * - Inside other annotation (`B` is annotation here): `@A(B()) fun foo(){}
+ */
+public data class KtAnnotationApplication(
+    /**
+     * The [ClassId] of applied annotation. [ClassId] is a fully qualified name on annotation class.
+     */
    public val classId: ClassId?,
+
+    /**
+     * PsiElement which was used to apply annotation to declaration/type.
+     *
+     * Present only for declarations from sources. For declarations from other places (libraries, stdlib) it's `null`
+     */
    public val psi: KtAnnotationEntry?,
+
+    /**
+     * [AnnotationUseSiteTarget] to which annotation was applied. May be not-null only for annotation applications for declarations.
+     *
+     * See in more details in [Kotlin Documentation](https://kotlinlang.org/docs/annotations.html#annotation-use-site-targets) for more information about annotation targets.
+     */
    public val useSiteTarget: AnnotationUseSiteTarget?,
+
+    /**
+     * A list of annotation arguments which were applied when constructing annotation. Every argument is [KtAnnotationValue]
+     */
    public val arguments: List<KtNamedAnnotationValue>,
 )
@@ -36,11 +36,17 @@ public sealed class KtAnnotationValue(
 */
 public object KtUnsupportedAnnotationValue : KtAnnotationValue()

+/**
+ * Array of annotation values. E.g: `@A([1, 2])`
+ */
 public class KtArrayAnnotationValue(
    public val values: Collection<KtAnnotationValue>,
    override val sourcePsi: KtElement?,
 ) : KtAnnotationValue()

+/**
+ * Other annotation used as argument. E.g: `@A(B)` where `B` is annotation too
+ */
 public class KtAnnotationApplicationValue(
    public val annotationValue: KtAnnotationApplication,
 ) : KtAnnotationValue() {
@@ -48,30 +54,73 @@ public class KtAnnotationApplicationValue(
 }


-public sealed class KtKClassAnnotationValue : KtAnnotationValue()
+/**
+ * Class reference used as annotation argument. E.g: `@A(String::class)`
+ */
+public sealed class KtKClassAnnotationValue : KtAnnotationValue() {
+    /**
+     * Non-local Class reference used as annotation value. E.g: `@A(String::class)`
+     */
+    public class KtNonLocalKClassAnnotationValue(
+        /**
+         * Fully qualified name of the class used
+         */
+        public val classId: ClassId,
+        override val sourcePsi: KtElement?,
+    ) : KtKClassAnnotationValue()

-public class KtNonLocalKClassAnnotationValue(
-    public val classId: ClassId,
-    override val sourcePsi: KtElement?,
-) : KtKClassAnnotationValue()
+    /**
+     * Non-local class reference used as annotation argument.
+     *
+     * E.g:
+     * ```
+     * fun x() {
+     *    class Y
+     *
+     *    @A(B::class)
+     *    fun foo() {}
+     * }
+     * ```
+     */
+    public class KtLocalKClassAnnotationValue(
+        /**
+         * [PsiElement] of the class used. As we can get non-local class only for sources, it is always present.
+         */
+        public val ktClass: KtClassOrObject,
+        override val sourcePsi: KtElement?,
+    ) : KtKClassAnnotationValue()

-public class KtLocalKClassAnnotationValue(
-    public val ktClass: KtClassOrObject,
-    override val sourcePsi: KtElement?,
-) : KtKClassAnnotationValue()
-
-public class KtErrorClassAnnotationValue(
-    override val sourcePsi: KtElement?,
-) : KtKClassAnnotationValue()
+    /**
+     * Non-existing class reference used as annotation argument. E.g: `@A(NON_EXISTING_CLASS::class)`
+     */
+    public class KtErrorClassAnnotationValue(
+        override val sourcePsi: KtElement?,
+    ) : KtKClassAnnotationValue()
+}

+/**
+ * Some enum entry (enum constant) used as annotation argument. E.g: `@A(Color.RED)`
+ */
 public class KtEnumEntryAnnotationValue(
+    /**
+     * Fully qualified name of used enum entry.
+     */
    public val callableId: CallableId?,
    override val sourcePsi: KtElement?,
 ) : KtAnnotationValue()

+/**
+ * Some constant value (which may be used as initializer of `const val`) used as annotation argument. It may be String literal, number literal or some simple expression.
+ * E.g: `@A(1 +2, "a" + "b")` -- both arguments here are [KtConstantAnnotationValue]
+ * @see [KtConstantValue]
+ */
 public class KtConstantAnnotationValue(
    public val constantValue: KtConstantValue,
 ) : KtAnnotationValue()

-public fun KtAnnotationValue.render(): String =
+
+/**
+ * Render annotation value, resulted string is a valid Kotlin source code.
+ */
+public fun KtAnnotationValue.renderAsSourceCode(): String =
    KtAnnotationValueRenderer.render(this)
@@ -7,8 +7,8 @@ package org.jetbrains.kotlin.analysis.api.annotations

 import org.jetbrains.kotlin.renderer.render

-public object KtAnnotationValueRenderer {
-    public fun render(value: KtAnnotationValue): String = buildString {
+internal object KtAnnotationValueRenderer {
+    fun render(value: KtAnnotationValue): String = buildString {
        renderConstantValue(value)
    }

@@ -37,9 +37,9 @@ public object KtAnnotationValueRenderer {

    private fun StringBuilder.renderKClassAnnotationValue(value: KtKClassAnnotationValue) {
        when (value) {
-            is KtErrorClassAnnotationValue -> append("UNRESOLVED_CLASS")
-            is KtLocalKClassAnnotationValue -> append(value.ktClass.nameAsName?.render())
-            is KtNonLocalKClassAnnotationValue -> append(value.classId.asSingleFqName().render())
+            is KtKClassAnnotationValue.KtErrorClassAnnotationValue -> append("UNRESOLVED_CLASS")
+            is KtKClassAnnotationValue.KtLocalKClassAnnotationValue -> append(value.ktClass.nameAsName?.render())
+            is KtKClassAnnotationValue.KtNonLocalKClassAnnotationValue -> append(value.classId.asSingleFqName().render())
        }
        append("::class")
    }
@@ -5,4 +5,9 @@

 package org.jetbrains.kotlin.analysis.api.annotations

-public data class KtNamedAnnotationValue(val name: String, val expression: KtAnnotationValue)
+import org.jetbrains.kotlin.name.Name
+
+/**
+ * Name-Value pair which is used as annotation argument.
+ */
+public data class KtNamedAnnotationValue(val name: Name, val expression: KtAnnotationValue)
@@ -9,10 +9,28 @@ import org.jetbrains.kotlin.psi.KtElement
 import org.jetbrains.kotlin.types.ConstantValueKind


+/**
+ * A Kotlin constant value. This value amy be used as `const val` initializer or annotation argument.
+ * Also, may represent evaluated constant value. So, `1 + 2` will be represented as `KtIntConstantValue(3)`
+ *
+ * For more info about constant values please see [official Kotlin documentation](https://kotlinlang.org/docs/properties.html#compile-time-constants])
+ */
 public sealed class KtConstantValue(public val constantValueKind: ConstantValueKind<*>) {
+    /**
+     * The constant value. The type of this value is always the type specified in its name, i.e, it is `Boolean` for [KtBooleanConstantValue]
+     *
+     * It is null only for [KtNullConstantValue]
+     */
    public abstract val value: Any?
+
+    /**
+     * Source element from which the value was created. May be null for constants from non-source files.
+     */
    public abstract val sourcePsi: KtElement?

+    /**
+     * Constant value represented as Kotlin code. E.g: `1`, `2f, `3u` `null`, `"str"`
+     */
    public abstract fun renderAsKotlinConstant(): String

    public class KtNullConstantValue(override val sourcePsi: KtElement?) : KtConstantValue(ConstantValueKind.Null) {
@@ -111,6 +129,9 @@ public sealed class KtConstantValue(public val constantValueKind: ConstantValueK
        override fun renderAsKotlinConstant(): String = value.toString()
    }

+    /**
+     * Value which is not cosntant or there was an error (e.g, division by 0) bug during value evaluation
+     */
    public class KtErrorConstantValue(
        public val errorMessage: String,
        override val sourcePsi: KtElement?,
@@ -20,6 +20,7 @@ import org.jetbrains.kotlin.analysis.utils.printer.PrettyPrinter
 import org.jetbrains.kotlin.analysis.utils.printer.prettyPrint
 import org.jetbrains.kotlin.descriptors.Visibility
 import org.jetbrains.kotlin.name.*
+import org.jetbrains.kotlin.renderer.render
 import java.lang.reflect.InvocationTargetException
 import kotlin.reflect.KClass
 import kotlin.reflect.KProperty
@@ -138,7 +139,7 @@ public object DebugSymbolRenderer {
    }

    private fun PrettyPrinter.renderNamedConstantValue(value: KtNamedAnnotationValue) {
-        append(value.name).append(" = ")
+        append(value.name.render()).append(" = ")
        renderValue(value.expression)
    }

@@ -45,7 +45,7 @@ private class FirNameValuePairForAnnotationArgument(
    override fun setValue(p0: PsiAnnotationMemberValue) = cannotModify()

    private val _nameIdentifier: PsiIdentifier by lazyPub {
-        LightIdentifier(parent.manager, constantValue.name)
+        LightIdentifier(parent.manager, constantValue.name.asString())
    }

    override fun getNameIdentifier(): PsiIdentifier = _nameIdentifier
@@ -54,5 +54,5 @@ private class FirNameValuePairForAnnotationArgument(

    override fun getLiteralValue(): String? = (value as? PsiLiteralExpression)?.value?.toString()

-    override fun getName(): String = constantValue.name
+    override fun getName(): String = constantValue.name.asString()
 }
@@ -202,13 +202,13 @@ internal fun KtAnnotationValue.toAnnotationMemberValue(parent: PsiElement): PsiA
            FirPsiExpression(sourcePsi, parent, psiExpression)
        }
        KtUnsupportedAnnotationValue -> null
-        is KtErrorClassAnnotationValue -> null
-        is KtLocalKClassAnnotationValue -> null
-        is KtNonLocalKClassAnnotationValue -> toAnnotationMemberValue(parent)
+        is KtKClassAnnotationValue.KtErrorClassAnnotationValue -> null
+        is KtKClassAnnotationValue.KtLocalKClassAnnotationValue -> null
+        is KtKClassAnnotationValue.KtNonLocalKClassAnnotationValue -> toAnnotationMemberValue(parent)
    }
 }

-private fun KtNonLocalKClassAnnotationValue.toAnnotationMemberValue(parent: PsiElement): PsiExpression? {
+private fun KtKClassAnnotationValue.KtNonLocalKClassAnnotationValue.toAnnotationMemberValue(parent: PsiElement): PsiExpression? {
    val fqName = classId.asSingleFqName()
    val canonicalText = psiType(
        fqName.asString(), parent, boxPrimitiveType = false /* TODO value.arrayNestedness > 0*/,