Add missing group and description for Multimodule tasks (#2806)

* Change warning level as requested #2806 (review) * Change the group of deprecated tasks to "deprecated" according to conversation https://github.com/Kotlin/dokka/pull/2806/files#r1093042654 * Use lazy resolution of tasks and explicit test for deprecation.
Kotlin · Feb 1, 2023 · ed6c67b · ed6c67b
1 parent fe360f7
commit ed6c67b
Show file tree

Hide file tree

Showing 3 changed files with 69 additions and 13 deletions.
diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTask.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTask.kt
@@ -9,7 +9,7 @@ import org.jetbrains.dokka.DokkaModuleDescriptionImpl
 import java.io.File
 
 @Suppress("unused") // Shall provide source compatibility if possible
-@Deprecated("Use 'DokkaMultimoduleTask' instead", ReplaceWith("DokkaMultimoduleTask"))
+@Deprecated("Use 'DokkaMultiModuleTask' instead", ReplaceWith("DokkaMultiModuleTask"), DeprecationLevel.ERROR)
 typealias DokkaMultimoduleTask = DokkaMultiModuleTask
 
 private typealias TaskPath = String

diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaPlugin.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaPlugin.kt
@@ -4,6 +4,7 @@ import org.gradle.api.DefaultTask
 import org.gradle.api.Plugin
 import org.gradle.api.Project
 import org.gradle.api.artifacts.Dependency
+import org.gradle.api.plugins.JavaBasePlugin
 import org.gradle.kotlin.dsl.register
 import org.gradle.util.GradleVersion
 
@@ -74,6 +75,8 @@ open class DokkaPlugin : Plugin<Project> {
                 }
 
                 project.tasks.register<DefaultTask>("${name}Multimodule") {
+                    group = "deprecated"
+                    description = "DEPRECATED: 'Multimodule' is deprecated. Use 'MultiModule' instead."
                     dependsOn(multiModuleName)
                     doLast {
                         logger.warn("'Multimodule' is deprecated. Use 'MultiModule' instead")

diff --git a/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaPluginApplyTest.kt b/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaPluginApplyTest.kt
@@ -1,6 +1,7 @@
 package org.jetbrains.dokka.gradle
 
 import org.gradle.api.plugins.JavaBasePlugin
+import org.gradle.api.tasks.TaskContainer
 import org.gradle.kotlin.dsl.withType
 import org.gradle.testfixtures.ProjectBuilder
 import kotlin.test.Test
@@ -55,24 +56,44 @@ class DokkaPluginApplyTest {
     fun `all dokka tasks are part of the documentation group`() {
         val project = ProjectBuilder.builder().build()
         project.plugins.apply("org.jetbrains.dokka")
-        project.tasks.filter { "dokka" in it.name.toLowerCase() }.forEach { dokkaTask ->
-            assertEquals(
-                JavaBasePlugin.DOCUMENTATION_GROUP, dokkaTask.group,
-                "Expected task: ${dokkaTask.path} group to be ${JavaBasePlugin.DOCUMENTATION_GROUP}"
-            )
-        }
+        assertDokkaTasksHaveDocumentationGroup(project.tasks)
+    }
+
+    @Test
+    fun `all dokka tasks are part of the documentation group in a multi module setup`() {
+        val root = ProjectBuilder.builder().withName("root").build()
+        val child = ProjectBuilder.builder().withName("child").withParent(root).build()
+        root.plugins.apply("org.jetbrains.dokka")
+        child.plugins.apply("org.jetbrains.dokka")
+        assertDokkaTasksHaveDocumentationGroup(root.tasks)
+        assertDokkaTasksHaveDocumentationGroup(child.tasks)
+    }
+
+    @Test
+    fun `old dokka tasks are part of the deprecated group in a multi module setup`() {
+        val root = ProjectBuilder.builder().withName("root").build()
+        val child = ProjectBuilder.builder().withName("child").withParent(root).build()
+        root.plugins.apply("org.jetbrains.dokka")
+        child.plugins.apply("org.jetbrains.dokka")
+        assertOldDokkaTasksHaveDeprecatedGroup(root.tasks)
+        assertOldDokkaTasksHaveDeprecatedGroup(child.tasks)
     }
 
     @Test
     fun `all dokka tasks provide a task description`() {
         val project = ProjectBuilder.builder().build()
         project.plugins.apply("org.jetbrains.dokka")
-        project.tasks.filter { "dokka" in it.name.toLowerCase() }.forEach { dokkaTask ->
-            assertTrue(
-                dokkaTask.description.orEmpty().isNotEmpty(),
-                "Expected description for task ${dokkaTask.name}"
-            )
-        }
+        assertDokkaTasksHaveDescription(project.tasks)
+    }
+
+    @Test
+    fun `all dokka tasks provide a task description in a multi module setup`() {
+        val root = ProjectBuilder.builder().withName("root").build()
+        val child = ProjectBuilder.builder().withName("child").withParent(root).build()
+        root.plugins.apply("org.jetbrains.dokka")
+        child.plugins.apply("org.jetbrains.dokka")
+        assertDokkaTasksHaveDescription(root.tasks)
+        assertDokkaTasksHaveDescription(child.tasks)
     }
 
     @Test
@@ -94,3 +115,35 @@ class DokkaPluginApplyTest {
         }
     }
 }
+
+private fun assertDokkaTasksHaveDocumentationGroup(taskContainer: TaskContainer) {
+    taskContainer.withType<AbstractDokkaTask>().forEach { dokkaTask ->
+        assertEquals(
+            JavaBasePlugin.DOCUMENTATION_GROUP,
+            dokkaTask.group,
+            "Expected task: ${dokkaTask.path} group to be \"${JavaBasePlugin.DOCUMENTATION_GROUP}\""
+        )
+    }
+}
+
+private fun assertOldDokkaTasksHaveDeprecatedGroup(taskContainer: TaskContainer) {
+    taskContainer.names.filter { "Multimodule" in it }.forEach { dokkaTaskName ->
+        val dokkaTask = taskContainer.getByName(dokkaTaskName)
+        val expectedGroup = "deprecated"
+        assertEquals(
+            expectedGroup,
+            dokkaTask.group,
+            "Expected task: ${dokkaTask.path} group to be \"${expectedGroup}\""
+        )
+    }
+}
+
+private fun assertDokkaTasksHaveDescription(taskContainer: TaskContainer) {
+    taskContainer.withType<AbstractDokkaTask>().forEach { dokkaTask ->
+        assertTrue(
+            @Suppress("UselessCallOnNotNull") // Task.description is nullable, but not inherited as Kotlin sees it.
+            dokkaTask.description.orEmpty().isNotEmpty(),
+            "Expected description for task ${dokkaTask.name}"
+        )
+    }
+}