Enhance kotlinx-metadata-jvm KDoc: add missing documentation, apply Grazie suggestions

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

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

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
+@MustBeDocumented
+annotation class UnstableMetadataApi

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
-)
+)

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.

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

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
+ * @property 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
+ * @property arguments Explicitly specified arguments to the annotation; does not include default values for annotation parameters
- *                  (specified in the annotation class declaration)
+ * (specified in the annotation class declaration)
  */
 class KmAnnotation(val className: ClassName, val arguments: Map<String, KmAnnotationArgument>) {
+
+    /**
+     * 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).

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<T> { fun <T> foo(t: T) }`)
+ *           the name is not enough (e.g. `class A<T> { fun <T> 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<in String?, *>`, `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"
 }
 

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,
 }