From 2845929bc09819a8538eef3ea104c951a98d098a Mon Sep 17 00:00:00 2001
From: Sebastian Sellmair <sebastian.sellmair@jetbrains.com>
Date: Fri, 23 Sep 2022 10:26:14 +0200
Subject: [PATCH] [Gradle][MPP] Add documentation to
 CompositeMetadataArtifactContent

^KT-54135 Verification Pending
---
 .../plugin/mpp/CompositeMetadataArtifact.kt   | 27 +++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/CompositeMetadataArtifact.kt b/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/CompositeMetadataArtifact.kt
index aa4fe1dad06..0f0f2d407a3 100644
--- a/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/CompositeMetadataArtifact.kt
+++ b/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/CompositeMetadataArtifact.kt
@@ -5,6 +5,7 @@
 
 package org.jetbrains.kotlin.gradle.plugin.mpp
 
+import org.jetbrains.kotlin.gradle.plugin.mpp.CompositeMetadataArtifactContent.SourceSetContent
 import java.io.Closeable
 import java.io.File
 
@@ -30,6 +31,32 @@ internal interface CompositeMetadataArtifact {
     }
 }
 
+
+/**
+ * This [CompositeMetadataArtifactContent] abstraction provides access into a metadata artifact published by a Multiplatform Library
+ *
+ * ### Example for the kotlinx.coroutines.core library
+ * During publication, kotlinx.coroutines.core will compile all its shared SourceSets individually into "kotlin metadata klib"s.
+ * e.g. a task called compileCommonMainKotlinMetadata will take the 'commonMain' SourceSet of the coroutines library
+ * and will produce a 'commonMain.klib' library which will contain only "Kotlin Metadata" (Signatures w/o any function bodies).
+ * Such klibs will be produced for all 'shared SourceSets'.
+ *
+ * During publication, all of those individual SourceSet klib binaries will be packaged into a 'jar' file called
+ * the Composite Metadata Artifact. All non-host specific klibs will be packaged and published in the root publication without target
+ * classifier (e.g. kotlinx-coroutines-core:
+ * https://repo1.maven.org/maven2/org/jetbrains/kotlinx/kotlinx-coroutines-core/1.6.4/kotlinx-coroutines-core-1.6.4-all.jar
+ *
+ * In the case of kotlinx.coroutines.core there will be [sourceSets] named 'commonMain', 'nativeMain', ....
+ * The commonMain.klib can therefore be accessed through the [SourceSetContent] of the
+ * 'commonMain' source set inside this [CompositeMetadataArtifactContent]
+ *
+ * e.g. copy the metadata klib of the 'commonMain' SourceSet into 'myFile'
+ * ```kotlin
+ * artifact.read { artifactContent ->
+ *     artifactContent.getSourceSet("commonMain").metadataBinary?.copyTo(myFile)
+ * }
+ * ```
+ */
 internal interface CompositeMetadataArtifactContent : Closeable {
     /**
      * Back reference to the [CompositeMetadataArtifact] that opened this [CompositeMetadataArtifactContent]