From 4de60879f030478f0d104dc81962514265f32c7b Mon Sep 17 00:00:00 2001 From: Yahor Berdnikau Date: Thu, 12 Jan 2023 10:47:14 +0100 Subject: [PATCH] Explicitly enable Dokka javadocs generation Actually we don't need javadoc generation for our internal stuff like ':kotlin-gradle-plugin'. But ':kotlin-gradle-plugin-api' is a public api and should have properly generated javadocs. ^KT-55520 In Progress --- buildSrc/src/main/kotlin/GradleCommon.kt | 98 +++++++-------- ...dle-plugin-common-configuration.gradle.kts | 1 - ...plugin-dependency-configuration.gradle.kts | 1 - .../kotlin-gradle-plugin-api/build.gradle.kts | 2 + .../tools/kotlin-gradle-plugin/Module.md | 117 ------------------ .../kotlin-gradle-plugin/build.gradle.kts | 9 -- 6 files changed, 47 insertions(+), 181 deletions(-) delete mode 100644 libraries/tools/kotlin-gradle-plugin/Module.md diff --git a/buildSrc/src/main/kotlin/GradleCommon.kt b/buildSrc/src/main/kotlin/GradleCommon.kt index a5f0e1b88c0..94bda8429a6 100644 --- a/buildSrc/src/main/kotlin/GradleCommon.kt +++ b/buildSrc/src/main/kotlin/GradleCommon.kt @@ -54,6 +54,8 @@ enum class GradlePluginVariant( GRADLE_76("gradle76", "7.6", "7.6"), } +val commonSourceSetName = "common" + /** * Configures common pom configuration parameters */ @@ -103,7 +105,7 @@ fun Project.excludeGradleCommonDependencies(sourceSet: SourceSet) { * Should contain classes that are independent of Gradle API version or using minimal supported Gradle api. */ fun Project.createGradleCommonSourceSet(): SourceSet { - val commonSourceSet = sourceSets.create("common") { + val commonSourceSet = sourceSets.create(commonSourceSetName) { excludeGradleCommonDependencies(this) // Adding Gradle API to separate configuration, so version will not leak into variants @@ -299,28 +301,6 @@ fun Project.reconfigureMainSourcesSetForGradlePlugin( } } - if (kotlinBuildProperties.publishGradlePluginsJavadoc) { - plugins.withId("org.jetbrains.dokka") { - val dokkaTask = tasks.named("dokkaJavadoc") { - dokkaSourceSets { - named(commonSourceSet.name) { - suppress.set(false) - } - - named("main") { - dependsOn(commonSourceSet) - } - } - } - - tasks.withType().configureEach { - if (name == javadocJarTaskName) { - from(dokkaTask.flatMap { it.outputDirectory }) - } - } - } - } - // Workaround for https://youtrack.jetbrains.com/issue/KT-52987 val javaComponent = project.components["java"] as AdhocComponentWithVariants listOf( @@ -446,36 +426,6 @@ fun Project.createGradlePluginVariant( } } - if (kotlinBuildProperties.publishGradlePluginsJavadoc) { - plugins.withId("org.jetbrains.dokka") { - val dokkaTask = tasks.register( - "dokka${ - variantSourceSet.javadocTaskName.replaceFirstChar { it.uppercase() } - }") { - description = "Generates documentation in 'javadoc' format for '${variantSourceSet.javadocTaskName}' variant" - - plugins.dependencies.add( - project.dependencies.create("org.jetbrains.dokka:javadoc-plugin:${DokkaVersion.version}") - ) - - dokkaSourceSets { - named(commonSourceSet.name) { - suppress.set(false) - } - - named(variantSourceSet.name) { - dependsOn(commonSourceSet) - suppress.set(false) - } - } - } - - tasks.named(variantSourceSet.javadocJarTaskName) { - from(dokkaTask.flatMap { it.outputDirectory }) - } - } - } - plugins.withId("java-gradle-plugin") { tasks.named(variantSourceSet.processResourcesTaskName) { val copyPluginDescriptors = rootSpec.addChild() @@ -632,4 +582,46 @@ fun Project.addBomCheckTask() { tasks.named("check") { dependsOn(checkBomTask) } +} + +fun Project.configureDokkaPublication() { + if (!kotlinBuildProperties.publishGradlePluginsJavadoc) return + + plugins.apply("org.jetbrains.dokka") + plugins.withId("org.jetbrains.dokka") { + val commonSourceSet = sourceSets.getByName(commonSourceSetName) + + GradlePluginVariant.values().forEach { pluginVariant -> + val variantSourceSet = sourceSets.getByName(pluginVariant.sourceSetName) + val dokkaTaskName = "dokka${variantSourceSet.javadocTaskName.replaceFirstChar { it.uppercase() }}" + + val dokkaTask = if (tasks.names.contains(dokkaTaskName)) { + tasks.named(dokkaTaskName) + } else { + tasks.register(dokkaTaskName) + } + dokkaTask.configure { + description = "Generates documentation in 'javadoc' format for '${variantSourceSet.javadocTaskName}' variant" + + plugins.dependencies.add( + project.dependencies.create("org.jetbrains.dokka:javadoc-plugin:${DokkaVersion.version}") + ) + + dokkaSourceSets { + named(commonSourceSet.name) { + suppress.set(false) + } + + named(variantSourceSet.name) { + dependsOn(commonSourceSet) + suppress.set(false) + } + } + } + + tasks.named(variantSourceSet.javadocJarTaskName) { + from(dokkaTask.flatMap { it.outputDirectory }) + } + } + } } \ No newline at end of file diff --git a/buildSrc/src/main/kotlin/gradle-plugin-common-configuration.gradle.kts b/buildSrc/src/main/kotlin/gradle-plugin-common-configuration.gradle.kts index 6f8eee9ce03..3a4ac28df4f 100644 --- a/buildSrc/src/main/kotlin/gradle-plugin-common-configuration.gradle.kts +++ b/buildSrc/src/main/kotlin/gradle-plugin-common-configuration.gradle.kts @@ -8,7 +8,6 @@ import plugins.signLibraryPublication plugins { kotlin("jvm") `java-gradle-plugin` - id("org.jetbrains.dokka") `maven-publish` id("com.gradle.plugin-publish") } diff --git a/buildSrc/src/main/kotlin/gradle-plugin-dependency-configuration.gradle.kts b/buildSrc/src/main/kotlin/gradle-plugin-dependency-configuration.gradle.kts index 8d5b1d2d03c..56c2d187075 100644 --- a/buildSrc/src/main/kotlin/gradle-plugin-dependency-configuration.gradle.kts +++ b/buildSrc/src/main/kotlin/gradle-plugin-dependency-configuration.gradle.kts @@ -9,7 +9,6 @@ import plugins.signLibraryPublication plugins { `java-library` kotlin("jvm") - id("org.jetbrains.dokka") `maven-publish` } diff --git a/libraries/tools/kotlin-gradle-plugin-api/build.gradle.kts b/libraries/tools/kotlin-gradle-plugin-api/build.gradle.kts index 9ed540ab9f6..4eae7103c03 100644 --- a/libraries/tools/kotlin-gradle-plugin-api/build.gradle.kts +++ b/libraries/tools/kotlin-gradle-plugin-api/build.gradle.kts @@ -4,6 +4,8 @@ plugins { id("org.jetbrains.kotlinx.binary-compatibility-validator") } +configureDokkaPublication() + dependencies { commonApi(platform(project(":kotlin-gradle-plugins-bom"))) commonApi(project(":kotlin-gradle-plugin-annotations")) diff --git a/libraries/tools/kotlin-gradle-plugin/Module.md b/libraries/tools/kotlin-gradle-plugin/Module.md deleted file mode 100644 index 862c3ec092d..00000000000 --- a/libraries/tools/kotlin-gradle-plugin/Module.md +++ /dev/null @@ -1,117 +0,0 @@ -# Module kotlin-gradle-plugin - -`kotlin-gradle-plugin` artifact provides multiple plugins. - -### kotlin - -How to apply: - -``` -apply plugin: 'kotlin' -``` - -Tasks: - -| Name | Type | Description -|------------------------------|--------------------|---------------| -| compileKotlin | [KotlinJvmCompile] | A task is created for `main` source set | -| compileTestKotlin | [KotlinJvmCompile] | A task is created for `test` source set | -| compile*SourceSetName*Kotlin | [KotlinJvmCompile] | A task is created for each additional source set | - -Each [KotlinJvmCompile] task provides `kotlinOptions` ([KotlinJvmOptions]) extension: - -``` -compileKotlin { - kotlinOptions { - noStdlib = true - } - // kotlinOptions.noStdlib = true -} -``` - -### kotlin-android - -A plugin that should be used for Android development. - -How to apply: - -``` -apply plugin: 'kotlin-android' -``` - -Tasks: - -| Name | Type | Description -|------------------------------|--------------------|---------------| -| compile*VariantName*Kotlin | [KotlinJvmCompile] | A task is created for each variant | - -Note that tasks are created after evaluation, so all references to tasks should be done in `afterEvaluate` section: - -``` -afterEvaluate { - compileDebugKotlin { - kotlinOptions { - noStdlib = true - } - } -} -``` - -Android plugin also adds `kotlinOptions` extension to `android` section to set options for all kotlin tasks: - -``` -android { - kotlinOptions { - noStdlib = true - } -} -``` - -Task's `kotlinOptions` "override" ones in `android` section: - -``` -android { - kotlinOptions { - noStdlib = true - } -} - -afterEvaluate { - compileDebugKotlin { - kotlinOptions { - noStdlib = false - } - } -} -// compileProductionKotlin.noStdlib == true -// compileDebugKotlin.noStdlib == false -``` - -### Kotlin/JS - -How to apply: - -``` -plugins { - id 'org.jetbrains.kotlin.js' -} -``` - -Tasks: - -| Name | Type | Description -|--------------------------------|--------------------|---------------| -| compileKotlin2Js | [KotlinJsCompile] | A task is created for `main` source set | -| compileTestKotlin2Js | [KotlinJsCompile] | A task is created for `test` source set | -| compile*SourceSetName*Kotlin2Js| [KotlinJsCompile] | A task is created for each additional source set | - -Each [KotlinJsCompile] task provides `kotlinOptions` ([KotlinJsOptions]) extension: - -``` -compileKotlinJs { - kotlinOptions { - noStdlib = true - } - // kotlinOptions.noStdlib = true -} -``` \ No newline at end of file diff --git a/libraries/tools/kotlin-gradle-plugin/build.gradle.kts b/libraries/tools/kotlin-gradle-plugin/build.gradle.kts index 0110042f8af..748187664ea 100644 --- a/libraries/tools/kotlin-gradle-plugin/build.gradle.kts +++ b/libraries/tools/kotlin-gradle-plugin/build.gradle.kts @@ -125,15 +125,6 @@ tasks { enableStricterValidation.set(true) } - withType().configureEach { - dokkaSourceSets.configureEach { - includes.from("Module.md") - } - } - register("dokka") { - dependsOn(named("dokkaJavadoc")) - } - withType().configureEach { relocate("com.github.gundy", "$kotlinEmbeddableRootPackage.com.github.gundy") relocate("de.undercouch.gradle.tasks.download", "$kotlinEmbeddableRootPackage.de.undercouch.gradle.tasks.download")