[Gradle][KPM] Minor: Cleanup imports, remove unused code and add documentation

libraries/tools/kotlin-gradle-plugin-api/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/KotlinDependencyConfigurations.kt

@@ -5,7 +5,6 @@
 
 package org.jetbrains.kotlin.gradle.plugin.mpp.pm20
 
-import org.gradle.api.NamedDomainObjectProvider
 import org.gradle.api.artifacts.Configuration
 
 interface KotlinDependencyConfigurations {

libraries/tools/kotlin-gradle-plugin-api/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/KotlinGradleVariant.kt

@@ -5,7 +5,6 @@
 
 package org.jetbrains.kotlin.gradle.plugin.mpp.pm20
 
-import org.gradle.api.NamedDomainObjectProvider
 import org.gradle.api.artifacts.Configuration
 import org.gradle.api.file.ConfigurableFileCollection
 import org.gradle.api.file.FileCollection

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/internal/KotlinDependenciesManagement.kt

@@ -48,7 +48,7 @@ internal fun customizeKotlinDependencies(project: Project) {
 }
 
 private fun configureDefaultVersionsResolutionStrategy(project: Project) {
-    project.configurations.configureEach { configuration ->
+    project.configurations.all { configuration ->
         // Use the API introduced in Gradle 4.4 to modify the dependencies directly before they are resolved:
         configuration.withDependencies { dependencySet ->
             val coreLibrariesVersion = project.topLevelExtension.coreLibrariesVersion

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/KotlinCompilationOutputsJarArtifactConfigurator.kt

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2010-2021 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package org.jetbrains.kotlin.gradle.plugin.mpp.pm20
+
+import org.gradle.api.artifacts.Configuration
+import org.gradle.jvm.tasks.Jar
+import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.util.disambiguateName
+import org.jetbrains.kotlin.gradle.tasks.locateOrRegisterTask
+import org.jetbrains.kotlin.gradle.utils.dashSeparatedName
+
+/**
+ * Registers a [Jar] task with the variant's compilation outputs and attaches this artifact to the given configuration.
+ */
+object KotlinCompilationOutputsJarArtifactConfigurator : KotlinFragmentConfigurationsConfigurator<KotlinGradleVariant> {
+    override fun configure(fragment: KotlinGradleVariant, configuration: Configuration) {
+        val jarTask = fragment.project.locateOrRegisterTask<Jar>(fragment.disambiguateName("jar")) {
+            it.from(fragment.compilationOutputs.allOutputs)
+            it.archiveClassifier.set(dashSeparatedName(fragment.name, fragment.containingModule.moduleClassifier))
+        }
+        fragment.project.artifacts.add(configuration.name, jarTask)
+    }
+}

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/KotlinFragmentConfigurationsConfigurator.kt

@@ -19,10 +19,23 @@ import org.jetbrains.kotlin.gradle.plugin.mpp.KotlinUsages.producerRuntimeUsage
 import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.util.ComputedCapability
 import org.jetbrains.kotlin.gradle.plugin.usageByName
 
+/**
+ * Special 'Configurator' for Gradle configurations.
+ * Such 'Configurator' depend on the concrete [KotlinGradleFragment] instance in order to run
+ * This 'Configurator's can be composed using the [KotlinConfigurationsConfigurator] or [plus] function.
+ */
 fun interface KotlinFragmentConfigurationsConfigurator<in T : KotlinGradleFragment> {
     fun configure(fragment: T, configuration: Configuration)
 }
 
+fun <T : KotlinGradleFragment> KotlinConfigurationsConfigurator(
+    vararg configurators: KotlinFragmentConfigurationsConfigurator<T>
+): KotlinFragmentConfigurationsConfigurator<T> {
+    return CompositeKotlinFragmentConfigurationsConfigurator(configurators.toList())
+}
+
+//region Simple default implementations
+
 object KotlinFragmentPlatformAttributesConfigurator : KotlinFragmentConfigurationsConfigurator<KotlinGradleVariant> {
     override fun configure(fragment: KotlinGradleVariant, configuration: Configuration) {
         configuration.attributes.attribute(KotlinPlatformType.attribute, fragment.platformType)
@@ -77,6 +90,8 @@ object KotlinFragmentModuleCapabilityConfigurator : KotlinFragmentConfigurations
     }
 }
 
+//endregion
+
 operator fun <T : KotlinGradleFragment> KotlinFragmentConfigurationsConfigurator<T>.plus(
     other: KotlinFragmentConfigurationsConfigurator<T>
 ): KotlinFragmentConfigurationsConfigurator<T> {
@@ -95,12 +110,6 @@ operator fun <T : KotlinGradleFragment> KotlinFragmentConfigurationsConfigurator
     return CompositeKotlinFragmentConfigurationsConfigurator(listOf(this, other))
 }
 
-fun <T : KotlinGradleFragment> KotlinConfigurationsConfigurator(
-    vararg configurators: KotlinFragmentConfigurationsConfigurator<T>
-): KotlinFragmentConfigurationsConfigurator<T> {
-    return CompositeKotlinFragmentConfigurationsConfigurator(configurators.toList())
-}
-
 private class CompositeKotlinFragmentConfigurationsConfigurator<in T : KotlinGradleFragment>(
     val setups: List<KotlinFragmentConfigurationsConfigurator<T>>
 ) : KotlinFragmentConfigurationsConfigurator<T> {

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/KotlinGradleFragment.kt

@@ -73,21 +73,6 @@ open class KotlinGradleFragmentInternal @Inject constructor(
     override fun dependencies(configureClosure: Closure<Any?>) =
         dependencies f@{ ConfigureUtil.configure(configureClosure, this@f) }
 
-    /*
-    override val apiConfigurationName: String
-        get() = disambiguateName("api")
-
-    override val implementationConfigurationName: String
-        get() = disambiguateName("implementation")
-
-    override val compileOnlyConfigurationName: String
-        get() = disambiguateName("compileOnly")
-
-    override val runtimeOnlyConfigurationName: String
-        get() = disambiguateName("runtimeOnly")
-
-     */
-
     private val _directRefinesDependencies = mutableSetOf<Provider<KotlinGradleFragment>>()
 
     override val directRefinesDependencies: Iterable<KotlinGradleFragment>

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/KotlinGradleFragmentFactory.kt

@@ -6,16 +6,40 @@
 package org.jetbrains.kotlin.gradle.plugin.mpp.pm20
 
 import org.gradle.api.NamedDomainObjectFactory
+import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.KotlinGradleFragmentFactory.FragmentConfigurator
+import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.KotlinGradleFragmentFactory.FragmentInstantiator
 
+/**
+ * Factory used by [KotlinGradleModule] to polymorphic-ally create fragments/variants.
+ * Fragments are created in two stages with this factory:
+ *
+ * [FragmentInstantiator]:
+ * An Instantiator (unlike something called a 'Factory') will just provide a new instance.
+ * All objects referenced from the Fragment shall be already created and accessing them should be safe,
+ * whilst some additional configuration still hase to be done in the configuration step.
+ *
+ * [FragmentConfigurator]:
+ *  After the fragment is instantiated, additional configuration (depending on the fragment instance) can be done.
+ *  Typical configurations are:
+ *   - Further setting up attributes of configurations (based upon the fragment itself)
+ *   - Setting up additional Gradle tasks
+ *   - Setting up publication
+ */
 class KotlinGradleFragmentFactory<T : KotlinGradleFragment>(
     private val fragmentInstantiator: FragmentInstantiator<T>,
     private val fragmentConfigurator: FragmentConfigurator<T>
 ) : NamedDomainObjectFactory<T> {
 
+    /**
+     * @see KotlinGradleFragmentFactory
+     */
     interface FragmentInstantiator<out T : KotlinGradleFragment> {
         fun create(name: String): T
     }
 
+    /**
+     * @see KotlinGradleFragmentFactory
+     */
     interface FragmentConfigurator<in T : KotlinGradleFragment> {
         fun configure(fragment: T)
     }

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/KotlinHostSpecificMetadataArtifactConfigurator.kt

@@ -14,6 +14,10 @@ import org.jetbrains.kotlin.gradle.tasks.registerTask
 import org.jetbrains.kotlin.library.KLIB_FILE_EXTENSION
 import org.jetbrains.kotlin.project.model.refinesClosure
 
+/**
+ * Will register a 'hostSpecificMetadataJar' [Jar] task containing compilation outputs of host specific metadata.
+ * Will add this jar artifact to the given configuration
+ */
 object KotlinHostSpecificMetadataArtifactConfigurator : KotlinGradleFragmentFactory.FragmentConfigurator<KotlinNativeVariantInternal> {
     override fun configure(fragment: KotlinNativeVariantInternal) {
         val project = fragment.project

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/KotlinJvmVariant.kt

@@ -5,7 +5,6 @@
 
 package org.jetbrains.kotlin.gradle.plugin.mpp.pm20
 
-import org.gradle.api.NamedDomainObjectProvider
 import org.gradle.api.artifacts.Configuration
 import org.gradle.api.plugins.BasePluginConvention
 import org.jetbrains.kotlin.gradle.dsl.KotlinJvmOptions

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/KotlinNativeVariant.kt

@@ -5,7 +5,6 @@
 
 package org.jetbrains.kotlin.gradle.plugin.mpp.pm20
 
-import org.gradle.api.NamedDomainObjectProvider
 import org.gradle.api.Project
 import org.gradle.api.artifacts.Configuration
 import org.jetbrains.kotlin.gradle.dsl.KotlinCommonOptions

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/configuration/KotlinApiElements.kt

@@ -8,12 +8,8 @@ package org.jetbrains.kotlin.gradle.plugin.mpp.pm20.configuration
 import org.gradle.api.artifacts.Configuration
 import org.gradle.api.attributes.Bundling
 import org.gradle.api.attributes.Category
-import org.gradle.jvm.tasks.Jar
 import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.*
 import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.util.FragmentNameDisambiguation
-import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.util.disambiguateName
-import org.jetbrains.kotlin.gradle.tasks.locateOrRegisterTask
-import org.jetbrains.kotlin.gradle.utils.dashSeparatedName
 
 interface KotlinApiElementsConfigurationInstantiator : KotlinFragmentConfigurationInstantiator
 
@@ -40,16 +36,3 @@ val DefaultKotlinApiElementsConfigurator = KotlinConfigurationsConfigurator(
     KotlinFragmentModuleCapabilityConfigurator,
     KotlinFragmentProducerApiUsageAttributesConfigurator
 )
-
-object KotlinCompilationOutputsJarArtifactConfigurator : KotlinFragmentConfigurationsConfigurator<KotlinGradleVariant> {
-    override fun configure(fragment: KotlinGradleVariant, configuration: Configuration) {
-        val project = fragment.project
-        val module = fragment.containingModule
-        val jarTaskName = fragment.disambiguateName("jar")
-        val jarTask = project.locateOrRegisterTask<Jar>(jarTaskName) {
-            it.from(fragment.compilationOutputs.allOutputs)
-            it.archiveClassifier.set(dashSeparatedName(fragment.name, module.moduleClassifier))
-        }
-        project.artifacts.add(configuration.name, jarTask)
-    }
-}

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/configuration/KotlinCompileDependencies.kt

@@ -5,11 +5,9 @@
 
 package org.jetbrains.kotlin.gradle.plugin.mpp.pm20.configuration
 
-import org.gradle.api.NamedDomainObjectProvider
 import org.gradle.api.artifacts.Configuration
 import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.*
 import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.util.FragmentNameDisambiguation
-import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.util.locateOrRegister
 import org.jetbrains.kotlin.gradle.utils.addExtendsFromRelation
 
 

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/configuration/KotlinRuntimeDependencies.kt

@@ -5,11 +5,9 @@
 
 package org.jetbrains.kotlin.gradle.plugin.mpp.pm20.configuration
 
-import org.gradle.api.NamedDomainObjectProvider
 import org.gradle.api.artifacts.Configuration
 import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.*
 import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.util.FragmentNameDisambiguation
-import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.util.locateOrRegister
 import org.jetbrains.kotlin.gradle.utils.addExtendsFromRelation
 
 interface KotlinRuntimeDependenciesConfigurationInstantiator : KotlinFragmentConfigurationInstantiator

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/util/KotlinFragmentNameDisambiguation.kt

@@ -18,6 +18,24 @@ internal fun FragmentNameDisambiguation(module: KotlinModule, fragmentName: Stri
     return DefaultKotlinFragmentNameDisambiguation(module, fragmentName)
 }
 
+/**
+ * Mechanism for disambiguating/scoping names for a certain fragment.
+ * e.g. Certain fragments might want to create a configuration called 'api'. However, the name scope
+ * of Gradle configurations is bound to the Gradle project which requires providing different names of mentioned configurations
+ * for FragmentFoo and FragmentBar.
+ *
+ * In such case a disambiguation _could_ produce:
+ *
+ * ```kotlin
+ * // in main module
+ * fragmentFoo.disambiguateName("api") == "fragmentFooApi"
+ * fragmentBar.disambiguateName("api") == "fragmentBarApi"
+ *
+ * // in test module
+ * fragmentFoo.disambiguateName("api") == "fragmentFooTestApi"
+ * fragmentBar.disambiguateName("api") == "fragmentBarTestApi"
+ * ```
+ */
 interface KotlinFragmentNameDisambiguation {
     fun disambiguateName(simpleName: String): String
 }

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/util/locateOrRegister.kt

@@ -1,14 +0,0 @@
-/*
- * Copyright 2010-2021 JetBrains s.r.o. and Kotlin Programming Language contributors.
- * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
- */
-
-package org.jetbrains.kotlin.gradle.plugin.mpp.pm20.util
-
-import org.gradle.api.NamedDomainObjectContainer
-import org.gradle.api.NamedDomainObjectProvider
-
-internal fun <T> NamedDomainObjectContainer<T>.locateOrRegister(name: String, configure: T.() -> Unit = {}): NamedDomainObjectProvider<T> {
-    return if (name in names) named(name, configure)
-    else register(name, configure)
-}

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/targets/android/internal/AndroidSubplugin.kt

@@ -50,7 +50,7 @@ class AndroidExtensionsSubpluginIndicator @Inject internal constructor(private v
     private fun addAndroidExtensionsRuntime(project: Project) {
         val kotlinPluginVersion = project.getKotlinPluginVersion()
 
-        project.configurations.configureEach all@{ configuration ->
+        project.configurations.all { configuration ->
             val name = configuration.name
             if (name != "implementation" && name != "compile") return@all
 

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/targets/native/DefaultCInteropSettings.kt

@@ -18,7 +18,6 @@ import org.jetbrains.kotlin.gradle.plugin.CInteropSettings.IncludeDirectories
 import org.jetbrains.kotlin.gradle.plugin.KotlinCompilation
 import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.KotlinNativeCompilationData
 import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.KotlinNativeVariantCompilationData
-import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.disambiguateName
 import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.util.disambiguateName
 import org.jetbrains.kotlin.gradle.targets.native.internal.CInteropIdentifier
 import org.jetbrains.kotlin.gradle.utils.lowerCamelCaseName