Remove usage of internal gradle classes in task dependencies

runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/AbstractDokkaParentTask.kt

@@ -2,81 +2,105 @@ package org.jetbrains.dokka.gradle
 
 import org.gradle.api.Project
 import org.gradle.api.Task
-import org.gradle.api.tasks.Internal
 import org.gradle.api.tasks.Nested
 import org.gradle.work.DisableCachingByDefault
 
+private const val DEPRECATION_MESSAGE = """
+    It is an anti-pattern to declare cross-project dependencies as it leads to various build problems. 
+    For this reason, this API wil be removed with the introduction of project isolation. 
+    When it happens, we will provide a migration guide. In the meantime, you can keep using this API
+    if you have to, but please don't rely on it if possible. If you don't want to document a certain project,
+    don't apply the Dokka plugin for it, or disable individual project tasks using the Gradle API .
+"""
+
+@Suppress("DEPRECATION")
 @DisableCachingByDefault(because = "Abstract super-class, not to be instantiated directly")
 abstract class AbstractDokkaParentTask : AbstractDokkaTask() {
 
-    @get:Internal
-    internal var childDokkaTaskPaths: Set<String> = emptySet()
-        private set
-
+    /**
+     * Dependencies from parent session (e.g. [DokkaMultiModuleTask] or [DokkaCollectorTask]) are stored
+     * in the common container [dependsOn] from gradle [Task].
+     * The [dependsOn] is a set and is available for everyone to write and has a type Object.
+     * We will live in our own subset of objects with a type [AbstractDokkaTask].
+     */
     @get:Nested
     internal val childDokkaTasks: Set<AbstractDokkaTask>
-        get() = childDokkaTaskPaths
-            .mapNotNull { path -> project.tasks.findByPath(path) }
-            .map(::checkIsAbstractDokkaTask)
+        get() = dependsOn
+            .filterIsInstance<AbstractDokkaTask>()
             .toSet()
 
     /* By task reference */
+    @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING)
     fun addChildTask(task: AbstractDokkaTask) {
-        childDokkaTaskPaths = childDokkaTaskPaths + task.path
+        dependsOn.add(task)
     }
 
+    @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING)
     fun removeChildTask(task: AbstractDokkaTask) {
-        childDokkaTaskPaths = childDokkaTaskPaths - task.path
+        setDependsOn(dependsOn.filter { it != task })
     }
 
     /* By path */
+    @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING)
     fun addChildTask(path: String) {
-        childDokkaTaskPaths = childDokkaTaskPaths + project.absoluteProjectPath(path)
+        // Skip the adding process if a task is not found:
+        // null will lead to the NPE failure during the dependency resolve process.
+        // case: dokka is not applied to some submodules
+        val task = project.tasks.findByPath(path) ?: return
+        addChildTask(task.asAbstractDokkaTask())
     }
 
+    @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING)
     fun removeChildTask(path: String) {
-        childDokkaTaskPaths = childDokkaTaskPaths - project.absoluteProjectPath(path)
+        setDependsOn(dependsOn.filterNot {
+            it is AbstractDokkaTask && it.path == project.absoluteProjectPath(path)
+        })
     }
 
     /* By project reference and name */
+    @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING)
     fun addChildTasks(projects: Iterable<Project>, childTasksName: String) {
         projects.forEach { project ->
             addChildTask(project.absoluteProjectPath(childTasksName))
         }
     }
 
+    @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING)
     fun removeChildTasks(projects: Iterable<Project>, childTasksName: String) {
         projects.forEach { project ->
             removeChildTask(project.absoluteProjectPath(childTasksName))
         }
     }
 
+    @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING)
     fun addSubprojectChildTasks(childTasksName: String) {
         addChildTasks(project.subprojects, childTasksName)
     }
 
+    @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING)
     fun removeSubprojectChildTasks(childTasksName: String) {
         removeChildTasks(project.subprojects, childTasksName)
     }
 
+    @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING)
     fun removeChildTasks(project: Project) {
-        childDokkaTaskPaths = childDokkaTaskPaths.filter { path ->
-            parsePath(path).parent != parsePath(project.path)
-        }.toSet()
+        setDependsOn(dependsOn.filterNot {
+            it is AbstractDokkaTask && parsePath(it.path).parent == parsePath(project.path)
+        })
     }
 
+    @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING)
     fun removeChildTasks(projects: Iterable<Project>) {
         projects.forEach { project -> removeChildTasks(project) }
     }
 
-    private fun checkIsAbstractDokkaTask(task: Task): AbstractDokkaTask {
-        if (task is AbstractDokkaTask) {
-            return task
-        }
+    private fun Task.asAbstractDokkaTask(): AbstractDokkaTask {
+        if (this is AbstractDokkaTask) return this
+
         throw IllegalArgumentException(
             "Only tasks of type ${AbstractDokkaTask::class.java.name} can be added as child for " +
                     "${AbstractDokkaParentTask::class.java.name} tasks.\n" +
-                    "Found task ${task.path} of type ${task::class.java.name} added to $path"
+                    "Found task ${this.path} of type ${this::class.java.name} added to ${this@AbstractDokkaParentTask.path}"
         )
     }
 }

runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTask.kt

@@ -1,7 +1,6 @@
 package org.jetbrains.dokka.gradle
 
 import org.gradle.api.file.ConfigurableFileCollection
-import org.gradle.api.internal.tasks.TaskDependencyInternal
 import org.gradle.api.provider.Property
 import org.gradle.api.tasks.*
 import org.jetbrains.dokka.DokkaConfigurationImpl
@@ -67,11 +66,6 @@ abstract class DokkaMultiModuleTask : AbstractDokkaParentTask() {
             task.path to task.dokkaSourceSets.flatMap { it.includes }.toSet()
         }
 
-    @Internal
-    override fun getTaskDependencies(): TaskDependencyInternal =
-        super.getTaskDependencies() + childDokkaTasks
-
-
     override fun generateDocumentation() {
         checkChildDokkaTasksIsNotEmpty()
         super.generateDocumentation()

runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaPlugin.kt

@@ -69,6 +69,7 @@ open class DokkaPlugin : Plugin<Project> {
                 project.maybeCreateDokkaRuntimeConfiguration(multiModuleName)
 
                 project.tasks.register<DokkaMultiModuleTask>(multiModuleName) {
+                    @Suppress("DEPRECATION")
                     addSubprojectChildTasks("${name}Partial")
                     configuration()
                     description = "Runs all subprojects '$name' tasks and generates module navigation page"
@@ -85,6 +86,7 @@ open class DokkaPlugin : Plugin<Project> {
             }
 
             project.tasks.register<DokkaCollectorTask>("${name}Collector") {
+                @Suppress("DEPRECATION")
                 addSubprojectChildTasks(name)
                 description =
                     "Generates documentation merging all subprojects '$name' tasks into one virtual module"

runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/checkChildDokkaTasksIsNotEmpty.kt

@@ -3,26 +3,10 @@ package org.jetbrains.dokka.gradle
 import org.jetbrains.dokka.DokkaException
 
 internal fun AbstractDokkaParentTask.checkChildDokkaTasksIsNotEmpty() {
-    if (childDokkaTaskPaths.isEmpty()) {
-        throw DokkaException(
-            """
-            The ${this::class.java.simpleName} $path has no configured child tasks. 
-            Add some dokka tasks like e.g.: 
-
-            tasks.named<AbstractDokkaParentTask>("$name") {
-                 addChildTask(..)
-                 addChildTasks(subprojects, "...")
-                 //...
-            }
-            """.trimIndent()
-        )
-    }
-
     if (childDokkaTasks.isEmpty()) {
         throw DokkaException(
             """
             The ${this::class.java.simpleName} $path could not find any registered child task. 
-            child tasks: $childDokkaTaskPaths
 
             Please make sure to apply the dokka plugin to all included (sub)-projects individually e.g.:
 
@@ -37,7 +21,7 @@ internal fun AbstractDokkaParentTask.checkChildDokkaTasksIsNotEmpty() {
             subprojects {
                 plugins.apply("org.jetbrains.dokka")
             }
-            """
+            """.trimIndent()
         )
     }
 }

runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/AbstractDokkaParentTaskTest.kt

@@ -1,7 +1,8 @@
+@file:Suppress("DEPRECATION")
+
 package org.jetbrains.dokka.gradle
 
 import org.gradle.api.Project
-import org.gradle.api.UnknownTaskException
 import org.gradle.kotlin.dsl.create
 import org.gradle.kotlin.dsl.getByName
 import org.gradle.testfixtures.ProjectBuilder
@@ -175,17 +176,16 @@ class AbstractDokkaParentTaskTest {
         )
     }
 
+    // scenario: some subprojects don't have dokka plugin applied, it will lead to import failure
     @Test
     fun `adding invalid path will not throw exception`() {
         parentTask.addChildTask(":some:stupid:path")
-        parentTask.childDokkaTasks
     }
 
     @Test
     fun `adding non dokka task will throw exception`() {
         val badTask = rootProject.tasks.create("badTask")
-        parentTask.addChildTask(badTask.path)
-        assertFailsWith<IllegalArgumentException> { parentTask.childDokkaTasks }
+        assertFailsWith<IllegalArgumentException> { parentTask.addChildTask(badTask.path) }
     }
 }
 

runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTaskTest.kt

@@ -1,4 +1,4 @@
-@file:Suppress("UnstableApiUsage")
+@file:Suppress("UnstableApiUsage", "DEPRECATION")
 
 package org.jetbrains.dokka.gradle