Fix DGPv2 migration helpers (#3822)

* Fix DGPv2 migration helpers

- Set the DGPv1 tasks to 'other' instead of "" (fix KT-71678)
- Configure all DGPv1 tasks, not just `DokkaTask`s.

dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/v2MigrationUtils.kt

@@ -9,10 +9,7 @@ import org.gradle.api.artifacts.ConfigurationContainer
 import org.gradle.internal.deprecation.DeprecatableConfiguration
 import org.gradle.kotlin.dsl.register
 import org.gradle.kotlin.dsl.withType
-import org.jetbrains.dokka.gradle.DokkaCollectorTask
-import org.jetbrains.dokka.gradle.DokkaMultiModuleTask
-import org.jetbrains.dokka.gradle.DokkaTask
-import org.jetbrains.dokka.gradle.DokkaTaskPartial
+import org.jetbrains.dokka.gradle.*
 import org.jetbrains.dokka.gradle.dependencies.DependencyContainerNames
 
 /**
@@ -36,8 +33,12 @@ internal fun addV2MigrationHelpers(
 }
 
 private fun configureDokkaTaskConventions(project: Project) {
-    project.tasks.withType<DokkaTask>().configureEach {
-        group = "" // hide from users
+    project.tasks.withType<AbstractDokkaTask>().configureEach {
+        // The DGPv1 tasks are only present to prevent buildscripts with references to them from breaking.
+        // The tasks are non-operable and should be hidden, to help nudge users to the DGPv2 tasks.
+        // Setting tasks with group null will hide it when running `gradle tasks`,
+        // and put it in the 'other' group in IntelliJ (which effectively hides it).
+        setGroup(null)
         onlyIf("Dokka V1 tasks are disabled due to the V2 flag being enabled") { false }
         enabled = false
         notCompatibleWithConfigurationCache("Dokka V1 tasks use deprecated Gradle features. Please migrate to Dokka Plugin V2, which fully supports Configuration Cache.")

dokka-runners/dokka-gradle-plugin/src/test/kotlin/internal/MigrationHelpersTest.kt

@@ -0,0 +1,107 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+package org.jetbrains.dokka.gradle.internal
+
+import io.kotest.core.spec.style.FunSpec
+import org.gradle.kotlin.dsl.withType
+import org.gradle.testfixtures.ProjectBuilder
+import org.jetbrains.dokka.gradle.AbstractDokkaTask
+import org.jetbrains.dokka.gradle.utils.enableV2Plugin
+import org.jetbrains.dokka.gradle.utils.shouldContainExactly
+
+class MigrationHelpersTest : FunSpec({
+    context("when multi-module project has DGPv2 with migration helpers enabled") {
+
+        val parentProject = ProjectBuilder.builder()
+            .build()
+            .enableV2Plugin(v2MigrationHelpers = true)
+
+        val childProject = ProjectBuilder.builder()
+            .withParent(parentProject)
+            .build()
+            .enableV2Plugin()
+            .enableV2Plugin(v2MigrationHelpers = true)
+
+        parentProject.plugins.apply("org.jetbrains.dokka")
+        childProject.plugins.apply("org.jetbrains.dokka")
+
+        context("in parent project") {
+            val parentProjectDokkaTasks = parentProject.tasks.withType<AbstractDokkaTask>()
+            test("all DGPv1 tasks should have group 'null'") {
+                val dokkaTasks = parentProjectDokkaTasks.associate { it.name to it.group }
+                dokkaTasks.shouldContainExactly(
+                    "dokkaGfm" to null,
+                    "dokkaGfmCollector" to null,
+                    "dokkaGfmMultiModule" to null,
+
+                    "dokkaHtml" to null,
+                    "dokkaHtmlCollector" to null,
+                    "dokkaHtmlMultiModule" to null,
+
+                    "dokkaJavadoc" to null,
+                    "dokkaJavadocCollector" to null,
+
+                    "dokkaJekyll" to null,
+                    "dokkaJekyllCollector" to null,
+                    "dokkaJekyllMultiModule" to null,
+                )
+            }
+            test("all DGPv1 tasks should be disabled") {
+                val dokkaTasks = parentProjectDokkaTasks.associate { it.name to it.enabled }
+                dokkaTasks.shouldContainExactly(
+                    "dokkaGfm" to false,
+                    "dokkaGfmCollector" to false,
+                    "dokkaGfmMultiModule" to false,
+
+                    "dokkaHtml" to false,
+                    "dokkaHtmlCollector" to false,
+                    "dokkaHtmlMultiModule" to false,
+
+                    "dokkaJavadoc" to false,
+                    "dokkaJavadocCollector" to false,
+
+                    "dokkaJekyll" to false,
+                    "dokkaJekyllCollector" to false,
+                    "dokkaJekyllMultiModule" to false,
+                )
+            }
+        }
+
+        context("in child project") {
+            val childProjectDokkaTasks = childProject.tasks.withType<AbstractDokkaTask>()
+            test("all DGPv1 tasks should have group 'null'") {
+                val dokkaTasks = childProjectDokkaTasks.associate { it.name to it.group }
+                dokkaTasks.shouldContainExactly(
+                    "dokkaGfm" to null,
+                    "dokkaGfmPartial" to null,
+
+                    "dokkaHtml" to null,
+                    "dokkaHtmlPartial" to null,
+
+                    "dokkaJavadoc" to null,
+                    "dokkaJavadocPartial" to null,
+
+                    "dokkaJekyll" to null,
+                    "dokkaJekyllPartial" to null,
+                )
+            }
+            test("all DGPv1 tasks should be disabled") {
+                val dokkaTasks = childProjectDokkaTasks.associate { it.name to it.enabled }
+                dokkaTasks.shouldContainExactly(
+                    "dokkaGfm" to false,
+                    "dokkaGfmPartial" to false,
+
+                    "dokkaHtml" to false,
+                    "dokkaHtmlPartial" to false,
+
+                    "dokkaJavadoc" to false,
+                    "dokkaJavadocPartial" to false,
+
+                    "dokkaJekyll" to false,
+                    "dokkaJekyllPartial" to false,
+                )
+            }
+        }
+    }
+})

dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/GradleProjectUtils.kt

@@ -6,9 +6,13 @@ package org.jetbrains.dokka.gradle.utils
 import org.gradle.api.Project
 
 fun Project.enableV2Plugin(
+    v2MigrationHelpers: Boolean = true,
     suppressV2Message: Boolean = true
 ): Project {
-    extensions.extraProperties.set("org.jetbrains.dokka.experimental.gradle.pluginMode", "V2Enabled")
+    extensions.extraProperties.set(
+        "org.jetbrains.dokka.experimental.gradle.pluginMode",
+        if (v2MigrationHelpers) "V2EnabledWithHelpers" else "V2Enabled",
+    )
     extensions.extraProperties.set("org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn", suppressV2Message)
     return this
 }