Deprecate methods for adding/removing task dependencies (#2857)

3 files changed, 24 insertions, 1 deletions

diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/AbstractDokkaParentTask.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/AbstractDokkaParentTask.kt
index 92314c52..e912b083 100644
--- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/AbstractDokkaParentTask.kt
+++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/AbstractDokkaParentTask.kt
@@ -6,6 +6,15 @@ 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() {
 
@@ -21,50 +30,60 @@ abstract class AbstractDokkaParentTask : AbstractDokkaTask() {
             .toSet()
 
     /* By task reference */
+    @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING)
     fun addChildTask(task: AbstractDokkaTask) {
         childDokkaTaskPaths = childDokkaTaskPaths + task.path
     }
 
+    @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING)
     fun removeChildTask(task: AbstractDokkaTask) {
         childDokkaTaskPaths = childDokkaTaskPaths - task.path
     }
 
     /* By path */
+    @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING)
     fun addChildTask(path: String) {
         childDokkaTaskPaths = childDokkaTaskPaths + project.absoluteProjectPath(path)
     }
 
+    @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING)
     fun removeChildTask(path: String) {
         childDokkaTaskPaths = childDokkaTaskPaths - 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()
     }
 
+    @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING)
     fun removeChildTasks(projects: Iterable<Project>) {
         projects.forEach { project -> removeChildTasks(project) }
     }
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
index 4186bdda..db2a219c 100644
--- 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
@@ -67,6 +67,9 @@ abstract class DokkaMultiModuleTask : AbstractDokkaParentTask() {
             task.path to task.dokkaSourceSets.flatMap { it.includes }.toSet()
         }
 
+    // The method contains a reference to internal Gradle API that is nice not to use.
+    // There was an attempt to get rid of it, but it was not successful
+    // See: https://github.com/Kotlin/dokka/pull/2835
     @Internal
     override fun getTaskDependencies(): TaskDependencyInternal =
         super.getTaskDependencies() + childDokkaTasks
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
index 4027f844..c6878963 100644
--- 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,7 +4,6 @@ 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
 
@@ -69,6 +68,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 +85,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"