diff --git a/libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/KotlinClassMetadata.kt b/libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/KotlinClassMetadata.kt index a5403621026..8e96dd36183 100644 --- a/libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/KotlinClassMetadata.kt +++ b/libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/KotlinClassMetadata.kt @@ -16,7 +16,7 @@ import java.util.* import kotlin.LazyThreadSafetyMode.PUBLICATION /** - * Represents the parsed metadata of a Kotlin JVM class file. + * Represents the parsed metadata of a Kotlin JVM class file. Entry point for parsing metadata on JVM. * * To create an instance of [KotlinClassMetadata], first obtain an instance of [Metadata] annotation on a class file, and then call [KotlinClassMetadata.read]. * [Metadata] annotation can be obtained either via reflection or created from data from a binary class file, using its constructor or helper function [kotlinx.metadata.jvm.Metadata]. @@ -28,9 +28,11 @@ import kotlin.LazyThreadSafetyMode.PUBLICATION * Normally, one would need at least a [Class] and a [FileFacade], as these are two most common kinds. * * Most of the subclasses offer a conversion method to transform metadata into a Km data structure — for example, [KotlinClassMetadata.Class.toKmClass]. - * Km data structures represent Kotlin declarations and offer variety of properties to introspect and alter them. + * Km data structures represent Kotlin declarations and offer a variety of properties to introspect and alter them. * Note that parsing may be lazy, depending on the implementation; therefore, one may not see an [IllegalArgumentException] indicating malformed metadata * until one calls `toKmClass` or a similar method. + * + * @property annotationData Raw contents of the metadata represented by [Metadata] annotation in the class file. */ sealed class KotlinClassMetadata(val annotationData: Metadata) { @@ -48,14 +50,14 @@ sealed class KotlinClassMetadata(val annotationData: Metadata) { /** * Returns a new [KmClass] instance created from this class metadata. * - * @throws IllegalArgumentException if metadata is malformed or inconsistent and can't be transformed into [KmClass]. + * @throws IllegalArgumentException if metadata is malformed or inconsistent and cannot be transformed into [KmClass]. */ fun toKmClass(): KmClass = wrapIntoMetadataExceptionWhenNeeded { KmClass().apply(this::accept) } /** - * Makes the given visitor visit metadata of this class. + * Makes the given visitor visit the metadata of this class. * * @param v the visitor that must visit this class */ @@ -99,7 +101,7 @@ sealed class KotlinClassMetadata(val annotationData: Metadata) { /** * Represents metadata of a class file containing a compiled Kotlin file facade. * - * File facade is a JVM class that contains declarations which do not belong to any Kotlin class: top-level functions, properties and type aliases. + * File facade is a JVM class that contains declarations which do not belong to any Kotlin class: top-level functions, properties, and type aliases. * For example, file Main.kt that contains only `fun main()` would produce a `MainKt.class` with FileFacade with this function metadata. * If Kotlin source file contains both classes and top-level declarations, only top-level declarations would be available in the corresponding file facade. * Classes would have their own JVM classfiles and their own metadata of [Class] kind. @@ -112,7 +114,7 @@ sealed class KotlinClassMetadata(val annotationData: Metadata) { /** * Creates a new [KmPackage] instance from this file facade metadata. * - * @throws IllegalArgumentException if metadata is malformed or inconsistent and can't be transformed into [KmPackage]. + * @throws IllegalArgumentException if metadata is malformed or inconsistent and cannot be transformed into [KmPackage]. */ fun toKmPackage(): KmPackage = wrapIntoMetadataExceptionWhenNeeded { KmPackage().apply(this::accept) @@ -175,7 +177,7 @@ sealed class KotlinClassMetadata(val annotationData: Metadata) { * Creates a new [KmLambda] instance from this synthetic class metadata. * Returns `null` if this synthetic class does not represent a lambda. * - * @throws IllegalArgumentException if metadata is malformed or inconsistent and can't be transformed into [KmLambda]. + * @throws IllegalArgumentException if metadata is malformed or inconsistent and cannot be transformed into [KmLambda]. */ fun toKmLambda(): KmLambda? = wrapIntoMetadataExceptionWhenNeeded { if (isLambda) KmLambda().apply(this::accept) else null @@ -188,7 +190,7 @@ sealed class KotlinClassMetadata(val annotationData: Metadata) { get() = annotationData.data1.isNotEmpty() /** - * Makes the given visitor visit metadata of this file facade, if this synthetic class represents a Kotlin lambda + * Makes the given visitor visit metadata of this file facade if this synthetic class represents a Kotlin lambda * (`isLambda` == true). * * Throws [IllegalArgumentException] if this synthetic class does not represent a Kotlin lambda. @@ -340,7 +342,7 @@ sealed class KotlinClassMetadata(val annotationData: Metadata) { /** * Creates a new [KmPackage] instance from this multi-file class part metadata. * - * @throws IllegalArgumentException if metadata is malformed or inconsistent and can't be transformed into [KmPackage]. + * @throws IllegalArgumentException if metadata is malformed or inconsistent and cannot be transformed into [KmPackage]. */ fun toKmPackage(): KmPackage = wrapIntoMetadataExceptionWhenNeeded { KmPackage().apply(this::accept) @@ -398,6 +400,10 @@ sealed class KotlinClassMetadata(val annotationData: Metadata) { */ class Unknown internal constructor(annotationData: Metadata) : KotlinClassMetadata(annotationData) + /** + * Collection of methods for reading and writing [KotlinClassMetadata], + * as well as metadata kind constants and [COMPATIBLE_METADATA_VERSION] constant. + */ companion object { /** * Writes contents of [kmClass] as the class metadata. @@ -589,7 +595,7 @@ sealed class KotlinClassMetadata(val annotationData: Metadata) { const val FILE_FACADE_KIND = 2 /** - * A class file kind signifying that the corresponding class file is synthetic, e.g. it's a class for lambda, `$DefaultImpls` class + * A class file kind signifying that the corresponding class file is synthetic, e.g. it is a class for lambda, `$DefaultImpls` class * for interface method implementations, `$WhenMappings` class for optimized `when` over enums, etc. * * @see Metadata.kind diff --git a/libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/KotlinModuleMetadata.kt b/libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/KotlinModuleMetadata.kt index 3a6d126d890..d7c044da2d8 100644 --- a/libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/KotlinModuleMetadata.kt +++ b/libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/KotlinModuleMetadata.kt @@ -104,7 +104,7 @@ class KotlinModuleMetadata private constructor( } /** - * Makes the given visitor visit metadata of this module file. + * Makes the given visitor visit the metadata of this module file. * * @param v the visitor that must visit this module file */ @@ -128,13 +128,16 @@ class KotlinModuleMetadata private constructor( v.visitEnd() } + /** + * Collection of methods for reading and writing [KotlinModuleMetadata]. + */ companion object { /** * Parses the given byte array with the .kotlin_module file content and returns the [KotlinModuleMetadata] instance, * or `null` if this byte array encodes a module with an unsupported metadata version. * * @throws IllegalArgumentException if an error happened while parsing the given byte array, - * which means that it's either not the content of a `.kotlin_module` file, or it has been corrupted. + * which means that it is either not the content of a `.kotlin_module` file, or it has been corrupted. */ @JvmStatic @UnstableMetadataApi diff --git a/libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/UnstableMetadataApi.kt b/libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/UnstableMetadataApi.kt index 88026cf1b66..5165fb5bf0d 100644 --- a/libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/UnstableMetadataApi.kt +++ b/libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/UnstableMetadataApi.kt @@ -6,7 +6,7 @@ package kotlinx.metadata.jvm /** - * Annotation marks an API that is still in development and not feature-complete or finalized. + * Marks an API that is still in development and not feature-complete or finalized. * Such an API does not provide compatibility guarantees. * It can be changed in future releases without migration aids or removed without replacement. */ @@ -14,4 +14,5 @@ package kotlinx.metadata.jvm "This part of API is not yet finished, does not provide any compatibility guarantees and can be changed in the future without notice", level = RequiresOptIn.Level.WARNING ) -annotation class UnstableMetadataApi \ No newline at end of file +@MustBeDocumented +annotation class UnstableMetadataApi diff --git a/libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/jvmMetadataUtil.kt b/libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/jvmMetadataUtil.kt index 858d9d28f2a..0d5f193d0e9 100644 --- a/libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/jvmMetadataUtil.kt +++ b/libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/jvmMetadataUtil.kt @@ -28,7 +28,7 @@ val ClassName.jvmInternalName: String get() = toJvmInternalName() /** * Helper function to instantiate [Metadata]. - * In contrary to direct constructor call, this one accept nullable parameters to substitute nulls with default values. + * Contrary to a direct constructor call, this one accepts nullable parameters to substitute nulls with default values. * Also, this one does not accept [Metadata.bytecodeVersion] as it is deprecated. */ fun Metadata( @@ -48,4 +48,4 @@ fun Metadata( extraString ?: "", packageName ?: "", extraInt ?: 0 -) \ No newline at end of file +) diff --git a/libraries/kotlinx-metadata/src/kotlinx/metadata/Flag.kt b/libraries/kotlinx-metadata/src/kotlinx/metadata/Flag.kt index cd09f9f5d89..194618950ef 100644 --- a/libraries/kotlinx-metadata/src/kotlinx/metadata/Flag.kt +++ b/libraries/kotlinx-metadata/src/kotlinx/metadata/Flag.kt @@ -54,6 +54,7 @@ class Flag(private val offset: Int, private val bitWidth: Int, private val value operator fun invoke(flags: Flags): Boolean = (flags ushr offset) and ((1 shl bitWidth) - 1) == value + /** @suppress deprecated in another PR */ companion object Common { /** * Signifies that the corresponding declaration has at least one annotation. diff --git a/libraries/kotlinx-metadata/src/kotlinx/metadata/OptInMarkers.kt b/libraries/kotlinx-metadata/src/kotlinx/metadata/OptInMarkers.kt index a3ec4279ba9..539baa074db 100644 --- a/libraries/kotlinx-metadata/src/kotlinx/metadata/OptInMarkers.kt +++ b/libraries/kotlinx-metadata/src/kotlinx/metadata/OptInMarkers.kt @@ -15,4 +15,5 @@ package kotlinx.metadata "The API is related to the experimental feature \"context receivers\" (see KEEP-259) and may be changed or removed in any future release.", RequiresOptIn.Level.ERROR ) +@MustBeDocumented annotation class ExperimentalContextReceivers diff --git a/libraries/kotlinx-metadata/src/kotlinx/metadata/annotations.kt b/libraries/kotlinx-metadata/src/kotlinx/metadata/annotations.kt index 2ca3c1d1cf5..523b6068f32 100644 --- a/libraries/kotlinx-metadata/src/kotlinx/metadata/annotations.kt +++ b/libraries/kotlinx-metadata/src/kotlinx/metadata/annotations.kt @@ -12,17 +12,29 @@ package kotlinx.metadata * On JVM, only annotations on type parameters and types are serialized to the Kotlin metadata * (see `KmType.annotations` and `KmTypeParameter.annotations` JVM extensions) * - * @param className the fully qualified name of the annotation class - * @param arguments explicitly specified arguments to the annotation; does not include default values for annotation parameters - * (specified in the annotation class declaration) + * @property className The fully qualified name of the annotation class + * @property arguments Explicitly specified arguments to the annotation; does not include default values for annotation parameters + * (specified in the annotation class declaration) */ class KmAnnotation(val className: ClassName, val arguments: Map) { + + /** + * Checks if this KmAnnotation is equal to the [other]. + * Instances of KmAnnotation are equal if they have same [className] and [arguments]. + */ override fun equals(other: Any?): Boolean = this === other || other is KmAnnotation && className == other.className && arguments == other.arguments + /** + * Returns hash code of this instance. + * Hash code is computed based on [className] and [arguments]. + */ override fun hashCode(): Int = 31 * className.hashCode() + arguments.hashCode() + /** + * Returns string representation of this instance with `@` sign, [className], and [arguments] in parenthesis. + */ override fun toString(): String { val args = arguments.toList().joinToString { (k, v) -> "$k = $v" } return "@$className($args)" @@ -119,7 +131,7 @@ sealed class KmAnnotationArgument { } /** - * An annotation argument with an array type, i.e. several values of one arbitrary type. + * An annotation argument with an array type, i.e., several values of one arbitrary type. * * For example, in `@Foo(["a", "b", "c"])` argument of `Foo` is an `ArrayValue` with [elements] * being a list of three [StringValue] elements: "a", "b", and "c" (without quotes). diff --git a/libraries/kotlinx-metadata/src/kotlinx/metadata/nodes.kt b/libraries/kotlinx-metadata/src/kotlinx/metadata/nodes.kt index 544120dd406..531a07f5715 100644 --- a/libraries/kotlinx-metadata/src/kotlinx/metadata/nodes.kt +++ b/libraries/kotlinx-metadata/src/kotlinx/metadata/nodes.kt @@ -304,7 +304,7 @@ class KmLambda : KmLambdaVisitor() { /** * Represents a constructor of a Kotlin class. * - * @property flags constructor flags, consisting of [Flag.HAS_ANNOTATIONS], visibility flag and [Flag.Constructor] flags + * @property flags constructor flags, consisting of [Flag.HAS_ANNOTATIONS], a visibility flag and [Flag.Constructor] flags */ @Suppress("DEPRECATION") class KmConstructor(var flags: Flags) : KmConstructorVisitor() { @@ -574,7 +574,7 @@ class KmTypeAlias( /** * Expanded type of the type alias, i.e. the full expansion of the underlying type, where all type aliases are substituted - * with their expanded types. If no type aliases are used in the underlying type, expanded type is equal to the underlying type. + * with their expanded types. If no type aliases are used in the underlying type, the expanded type is equal to the underlying type. */ lateinit var expandedType: KmType @@ -690,7 +690,7 @@ class KmValueParameter( * @property flags type parameter flags, consisting of [Flag.TypeParameter] flags * @property name the name of the type parameter * @property id the id of the type parameter, useful to be able to uniquely identify the type parameter in different contexts where - * the name isn't enough (e.g. `class A { fun foo(t: T) }`) + * the name is not enough (e.g. `class A { fun foo(t: T) }`) * @property variance the declaration-site variance of the type parameter */ @Suppress("DEPRECATION") @@ -853,7 +853,7 @@ class KmType(var flags: Flags) : KmTypeVisitor() { * Represents a version requirement on a Kotlin declaration. * * Version requirement is an internal feature of the Kotlin compiler and the standard Kotlin library, - * enabled for example with the internal [kotlin.internal.RequireKotlin] annotation. + * enabled, for example, with the internal [kotlin.internal.RequireKotlin] annotation. */ @Suppress("DEPRECATION") class KmVersionRequirement : KmVersionRequirementVisitor() { @@ -1002,7 +1002,7 @@ class KmEffectExpression : KmEffectExpressionVisitor() { /** * Optional 1-based index of the value parameter of the function, for effects which assert something about - * the function parameters. The index 0 means the extension receiver parameter. + * the function parameters. Index 0 means the extension receiver parameter. */ var parameterIndex: Int? = null @@ -1068,7 +1068,7 @@ class KmEffectExpression : KmEffectExpressionVisitor() { } /** - * Represents a classifier of a Kotlin type. A classifier is a class, type parameter or type alias. + * Represents a classifier of a Kotlin type. A classifier is a class, type parameter, or type alias. * For example, in `MutableMap`, `MutableMap` is the classifier. */ sealed class KmClassifier { @@ -1103,6 +1103,9 @@ sealed class KmClassifier { * @property type the projected type, or `null` if this is a star projection */ data class KmTypeProjection(var variance: KmVariance?, var type: KmType?) { + /** + * Contains default instance for star projection: [KmTypeProjection.STAR]. + */ companion object { /** * Star projection (`*`). @@ -1130,6 +1133,10 @@ data class KmFlexibleTypeUpperBound(var type: KmType, var typeFlexibilityId: Str * @property patch the patch component of the version (e.g. "3" in "1.2.3") */ data class KmVersion(val major: Int, val minor: Int, val patch: Int) { + + /** + * Returns a string representation of this version in "$major.$minor.$patch" form. + */ override fun toString(): String = "$major.$minor.$patch" } diff --git a/libraries/kotlinx-metadata/src/kotlinx/metadata/visitors.kt b/libraries/kotlinx-metadata/src/kotlinx/metadata/visitors.kt index 3cbe1243e37..66674e5325a 100644 --- a/libraries/kotlinx-metadata/src/kotlinx/metadata/visitors.kt +++ b/libraries/kotlinx-metadata/src/kotlinx/metadata/visitors.kt @@ -897,8 +897,26 @@ enum class KmVariance { */ @ExperimentalContracts enum class KmEffectType { + /** + * Represents `returns(value)` contract effect: + * a situation when a function returns normally with the specified return value. + * Return value is stored in the [KmEffect.constructorArguments]. + */ RETURNS_CONSTANT, + + /** + * Represents `callsInPlace` contract effect: + * A situation when the referenced lambda is invoked in place (optionally) specified number of times. + * + * Referenced lambda is stored in the [KmEffect.constructorArguments]. + * Number of invocations, if specified, is stored in [KmEffect.invocationKind]. + */ CALLS, + + /** + * Represents `returnsNotNull` contract effect: + * a situation when a function returns normally with any value that is not null. + */ RETURNS_NOT_NULL, } @@ -910,8 +928,19 @@ enum class KmEffectType { */ @ExperimentalContracts enum class KmEffectInvocationKind { + /** + * A function parameter will be invoked one time or not invoked at all. + */ AT_MOST_ONCE, + + /** + * A function parameter will be invoked exactly one time. + */ EXACTLY_ONCE, + + /** + * A function parameter will be invoked one or more times. + */ AT_LEAST_ONCE, } @@ -919,8 +948,19 @@ enum class KmEffectInvocationKind { * Severity of the diagnostic reported by the compiler when a version requirement is not satisfied. */ enum class KmVersionRequirementLevel { + /** + * Represents a diagnostic with 'WARNING' severity. + */ WARNING, + + /** + * Represents a diagnostic with 'ERROR' severity. + */ ERROR, + + /** + * Excludes the declaration from the resolution process completely when the version requirement is not satisfied. + */ HIDDEN, } @@ -928,7 +968,18 @@ enum class KmVersionRequirementLevel { * The kind of the version that is required by a version requirement. */ enum class KmVersionRequirementVersionKind { + /** + * Indicates that certain language version is required. + */ LANGUAGE_VERSION, + + /** + * Indicates that certain compiler version is required. + */ COMPILER_VERSION, + + /** + * Indicates that certain API version is required. + */ API_VERSION, }