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
@@ -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)
    }