Add docs for different metadata versions and proto files

Review: https://jetbrains.team/p/kt/reviews/8401
In scope of KT-55082

compiler/util-klib-metadata/src/KlibMetadataProtoBuf.proto

@@ -16,6 +16,8 @@
 
 package org.jetbrains.kotlin.library.metadata;
 
+// Changes to this proto are tracked by KlibMetadataVersion version. See KlibMetadataVersion KDoc.
+
 import "core/metadata/src/metadata.proto";
 import "core/metadata/src/ext_options.proto";
 

compiler/util-klib-metadata/src/org/jetbrains/kotlin/library/metadata/KlibDeserializedContainerSource.kt

@@ -34,7 +34,7 @@ class KlibDeserializedContainerSource private constructor(
     )
 
     override val incompatibility: IncompatibleVersionErrorData<*>?
-        get() = null
+        get() = null // TODO KT-55808
 
     override val abiStability: DeserializedContainerAbiStability
         get() = DeserializedContainerAbiStability.STABLE

compiler/util-klib-metadata/src/org/jetbrains/kotlin/library/metadata/KlibMetadataMetadataVersion.kt

@@ -9,6 +9,19 @@ import org.jetbrains.kotlin.library.KLIB_PROPERTY_METADATA_VERSION
 import org.jetbrains.kotlin.library.KotlinLibrary
 import org.jetbrains.kotlin.metadata.deserialization.BinaryVersion
 
+/**
+ * The version for `KlibMetadataProtoBuf.proto`. This version also includes the version of the core protobuf messages (`metadata.proto`).
+ *
+ * This version must be bumped when:
+ * - Incompatible changes are made in `KlibMetadataProtoBuf.proto`
+ * - Incompatible changes are made in `metadata.proto`
+ * - Incompatible changes are made in Klib metadata serialization/deserialization logic
+ *
+ * The version bump must obey [org.jetbrains.kotlin.metadata.deserialization.BinaryVersion] rules (See `BinaryVersion` KDoc).
+ *
+ * Known bugs: [KlibMetadataVersion] isn't currently checked for klibs [KT-55808](https://youtrack.jetbrains.com/issue/KT-55808)
+ * [KT-56062](https://youtrack.jetbrains.com/issue/KT-56062).
+ */
 class KlibMetadataVersion(vararg numbers: Int) : BinaryVersion(*numbers) {
 
     override fun isCompatibleWithCurrentCompilerVersion(): Boolean = isCompatibleTo(INSTANCE)