Deprecate DGPv1 types (#4135)

* Deprecate DGPv1 types

Deprecate all DGPv1 mode public APIs. This will help users migrating to v2 DGPv2 to clean up leftover DGPv1 code.

Added `@Suppress("DEPRECATION")` to internal usages of the deprecated types to avoid noisy warnings.
I made the suppressions as targeted as possible, to avoid accidental suppression from Gradle types.

#4098

* fix kotlinx serialization test

* rm unused copyChildOutputDirectories function

Author: adam-enko

dokka-integration-tests/README.md

@@ -46,6 +46,11 @@ Here's how to update an external project:
    git diff > $pathToProjectInDokka/project.diff
    ```
 
+   Or, on macOS, copied to the clipboard:
+   ```shell
+   git diff | pbcopy
+   ```
+
 4. Check that the corresponding `GradleIntegrationTest` passes locally and push
 
 ### Example projects

dokka-integration-tests/gradle/projects/serialization/serialization.diff

@@ -1,5 +1,5 @@
 diff --git a/build.gradle.kts b/build.gradle.kts
-index f2cfd853..028c590d 100644
+index f2cfd853..b74e188a 100644
 --- a/build.gradle.kts
 +++ b/build.gradle.kts
 @@ -21,13 +21,13 @@ plugins {
@@ -26,7 +26,13 @@ index f2cfd853..028c590d 100644
          mavenCentral()
          maven("https://cache-redirector.jetbrains.com/maven.pkg.jetbrains.space/kotlin/p/kotlin/dev")
      }
-@@ -143,7 +144,20 @@ tasks.withType<DokkaMultiModuleTask>().named("dokkaHtmlMultiModule") {
+@@ -138,12 +139,25 @@ tasks.register("dokka") {
+     dependsOn("dokkaHtmlMultiModule")
+ }
+
+-tasks.withType<DokkaMultiModuleTask>().named("dokkaHtmlMultiModule") {
++tasks.withType<@Suppress("DEPRECATION") DokkaMultiModuleTask>().named("dokkaHtmlMultiModule") {
+     pluginsMapConfiguration.put("org.jetbrains.dokka.base.DokkaBase", """{ "templatesDir": "${projectDir.toString().replace("\\", "/")}/dokka-templates" }""")
  }
 
  dependencies {
@@ -77,7 +83,7 @@ index 529b81c1..218558c2 100644
 
  kotlin {
 diff --git a/buildSrc/settings.gradle.kts b/buildSrc/settings.gradle.kts
-index b450fd5e..9f189439 100644
+index b450fd5e..927b34b9 100644
 --- a/buildSrc/settings.gradle.kts
 +++ b/buildSrc/settings.gradle.kts
 @@ -14,6 +14,7 @@ dependencyResolutionManagement {
@@ -88,11 +94,27 @@ index b450fd5e..9f189439 100644
          }
      }
  }
+@@ -48,4 +49,4 @@ fun overriddenKotlinVersion(): String? {
+         return trainVersion ?: trainVersionFile ?: throw IllegalArgumentException("\"kotlin_snapshot_version\" should be defined when building with snapshot compiler")
+     }
+     return null
+-}
+\ No newline at end of file
++}
 diff --git a/buildSrc/src/main/kotlin/dokka-conventions.gradle.kts b/buildSrc/src/main/kotlin/dokka-conventions.gradle.kts
-index d3013727..0c443aa4 100644
+index d3013727..b58ad96a 100644
 --- a/buildSrc/src/main/kotlin/dokka-conventions.gradle.kts
 +++ b/buildSrc/src/main/kotlin/dokka-conventions.gradle.kts
-@@ -15,7 +15,12 @@ plugins {
+@@ -2,6 +2,8 @@
+  * Copyright 2017-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+  */
+
++@file:Suppress("DEPRECATION")
++
+ import org.jetbrains.dokka.gradle.*
+ import java.net.URI
+
+@@ -15,7 +17,12 @@ plugins {
 
  val extens = extensions
  dependencies {
@@ -106,6 +128,39 @@ index d3013727..0c443aa4 100644
  }
 
  tasks.withType<DokkaTaskPartial>().named("dokkaHtmlPartial") {
+@@ -76,4 +83,4 @@ tasks.withType<DokkaTaskPartial>().named("dokkaHtmlPartial") {
+             }
+         }
+     }
+-}
+\ No newline at end of file
++}
+diff --git a/formats/json-io/build.gradle.kts b/formats/json-io/build.gradle.kts
+index 2effe4f2..0adb4f1e 100644
+--- a/formats/json-io/build.gradle.kts
++++ b/formats/json-io/build.gradle.kts
+@@ -33,7 +33,7 @@ kotlin {
+
+ project.configureJava9ModuleInfo()
+
+-tasks.named<DokkaTaskPartial>("dokkaHtmlPartial") {
++tasks.named<@Suppress("DEPRECATION") DokkaTaskPartial>("dokkaHtmlPartial") {
+     dokkaSourceSets {
+         configureEach {
+             externalDocumentationLink {
+diff --git a/formats/json-okio/build.gradle.kts b/formats/json-okio/build.gradle.kts
+index 93513985..42b93ac2 100644
+--- a/formats/json-okio/build.gradle.kts
++++ b/formats/json-okio/build.gradle.kts
+@@ -34,7 +34,7 @@ kotlin {
+
+ project.configureJava9ModuleInfo()
+
+-tasks.named<DokkaTaskPartial>("dokkaHtmlPartial") {
++tasks.named<@Suppress("DEPRECATION") DokkaTaskPartial>("dokkaHtmlPartial") {
+     dokkaSourceSets {
+         configureEach {
+             externalDocumentationLink {
 diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
 index 132a67b6..b851a68c 100644
 --- a/gradle/libs.versions.toml

dokka-runners/dokka-gradle-plugin/src/classicMain/kotlin/DokkaClassicPlugin.kt

@@ -11,12 +11,14 @@ import org.gradle.kotlin.dsl.register
 import org.gradle.kotlin.dsl.withType
 import org.gradle.util.GradleVersion
 import org.jetbrains.dokka.DokkaDefaults
+import org.jetbrains.dokka.gradle.DOKKA_V1_DEPRECATION_MESSAGE
 
 /**
  * The OG Dokka Gradle Plugin. A.K.A. DGP Classic, or Dokka V1.
  *
  * This plugin is planned for removal, see https://youtrack.jetbrains.com/issue/KT-71027/Remove-Dokka-Gradle-Plugin-v1
  */
+@Deprecated(DOKKA_V1_DEPRECATION_MESSAGE)
 open class DokkaClassicPlugin : Plugin<Project> {
     override fun apply(project: Project) {
         if (GradleVersion.version(project.gradle.gradleVersion) < GradleVersion.version("5.6")) {
@@ -63,19 +65,19 @@ open class DokkaClassicPlugin : Plugin<Project> {
         name: String,
         multiModuleTaskSupported: Boolean = true,
         allModulesPageAndTemplateProcessing: Dependency = project.dokkaArtifacts.allModulesPage,
-        configuration: AbstractDokkaTask.() -> Unit = {}
+        configuration: @Suppress("DEPRECATION") AbstractDokkaTask.() -> Unit = {}
     ) {
         project.maybeCreateDokkaPluginConfiguration(name)
         project.maybeCreateDokkaRuntimeConfiguration(name)
-        project.tasks.register<DokkaTask>(name) {
+        project.tasks.register<@Suppress("DEPRECATION") DokkaTask>(name) {
             configuration()
         }
 
         if (project.parent != null) {
             val partialName = "${name}Partial"
             project.maybeCreateDokkaPluginConfiguration(partialName)
             project.maybeCreateDokkaRuntimeConfiguration(partialName)
-            project.tasks.register<DokkaTaskPartial>(partialName) {
+            project.tasks.register<@Suppress("DEPRECATION") DokkaTaskPartial>(partialName) {
                 configuration()
             }
         }
@@ -86,7 +88,7 @@ open class DokkaClassicPlugin : Plugin<Project> {
                 project.maybeCreateDokkaPluginConfiguration(multiModuleName, setOf(allModulesPageAndTemplateProcessing))
                 project.maybeCreateDokkaRuntimeConfiguration(multiModuleName)
 
-                project.tasks.register<DokkaMultiModuleTask>(multiModuleName) {
+                project.tasks.register<@Suppress("DEPRECATION") DokkaMultiModuleTask>(multiModuleName) {
                     @Suppress("DEPRECATION")
                     addSubprojectChildTasks("${name}Partial")
                     configuration()
@@ -103,7 +105,7 @@ open class DokkaClassicPlugin : Plugin<Project> {
                 }
             }
 
-            project.tasks.register<DokkaCollectorTask>("${name}Collector") {
+            project.tasks.register<@Suppress("DEPRECATION") DokkaCollectorTask>("${name}Collector") {
                 @Suppress("DEPRECATION")
                 addSubprojectChildTasks(name)
                 description =
@@ -113,7 +115,7 @@ open class DokkaClassicPlugin : Plugin<Project> {
     }
 
     private fun Project.configureEachAbstractDokkaTask() {
-        tasks.withType<AbstractDokkaTask>().configureEach task@{
+        tasks.withType<@Suppress("DEPRECATION") AbstractDokkaTask>().configureEach task@{
             val formatClassifier = name.removePrefix("dokka").decapitalize()
             outputDirectory.convention(project.layout.buildDirectory.dir("dokka/$formatClassifier"))
             cacheRoot.convention(project.layout.dir(providers.provider { DokkaDefaults.cacheRoot }))
@@ -124,7 +126,7 @@ open class DokkaClassicPlugin : Plugin<Project> {
     }
 
     private fun Project.configureEachDokkaMultiModuleTask() {
-        tasks.withType<DokkaMultiModuleTask>().configureEach {
+        tasks.withType<@Suppress("DEPRECATION") DokkaMultiModuleTask>().configureEach {
             sourceChildOutputDirectories.from({ childDokkaTasks.map { it.outputDirectory } })
         }
     }

dokka-runners/dokka-gradle-plugin/src/classicMain/kotlin/DokkaMultiModuleFileLayout.kt

@@ -7,15 +7,14 @@ package org.jetbrains.dokka.gradle
 import org.gradle.api.file.Directory
 import org.gradle.api.provider.Provider
 import org.jetbrains.dokka.DokkaException
-import org.jetbrains.dokka.gradle.DokkaMultiModuleFileLayout.CompactInParent
-import org.jetbrains.dokka.gradle.DokkaMultiModuleFileLayout.NoCopy
 import java.io.File
 
 /**
  * @see DokkaMultiModuleFileLayout.targetChildOutputDirectory
- * @see NoCopy
- * @see CompactInParent
+ * @see org.jetbrains.dokka.gradle.DokkaMultiModuleFileLayout.NoCopy
+ * @see org.jetbrains.dokka.gradle.DokkaMultiModuleFileLayout.CompactInParent
  */
+@Deprecated(DOKKA_V1_DEPRECATION_MESSAGE)
 fun interface DokkaMultiModuleFileLayout {
 
     /**
@@ -24,15 +23,19 @@ fun interface DokkaMultiModuleFileLayout {
      * @return The target output directory of the [child] dokka task referenced by [parent]. This should
      * be unique for all registered child tasks.
      */
-    fun targetChildOutputDirectory(parent: DokkaMultiModuleTask, child: AbstractDokkaTask): Provider<Directory>
+    fun targetChildOutputDirectory(
+        parent: @Suppress("DEPRECATION") DokkaMultiModuleTask,
+        child: @Suppress("DEPRECATION") AbstractDokkaTask
+    ): Provider<Directory>
 
     /**
      * Will link to the original [AbstractDokkaTask.outputDirectory]. This requires no copying of the output files.
      */
-    object NoCopy : DokkaMultiModuleFileLayout {
+    @Deprecated(DOKKA_V1_DEPRECATION_MESSAGE)
+    object NoCopy : @Suppress("DEPRECATION") DokkaMultiModuleFileLayout {
         override fun targetChildOutputDirectory(
-            parent: DokkaMultiModuleTask,
-            child: AbstractDokkaTask
+            parent: @Suppress("DEPRECATION") DokkaMultiModuleTask,
+            child: @Suppress("DEPRECATION") AbstractDokkaTask
         ): Provider<Directory> = child.outputDirectory
     }
 
@@ -43,10 +46,11 @@ fun interface DokkaMultiModuleFileLayout {
      * :parentProject:firstAncestor:secondAncestor will be be resolved to
      * {parent output directory}/firstAncestor/secondAncestor
      */
-    object CompactInParent : DokkaMultiModuleFileLayout {
+    @Deprecated(DOKKA_V1_DEPRECATION_MESSAGE)
+    object CompactInParent : @Suppress("DEPRECATION") DokkaMultiModuleFileLayout {
         override fun targetChildOutputDirectory(
-            parent: DokkaMultiModuleTask,
-            child: AbstractDokkaTask
+            parent: @Suppress("DEPRECATION") DokkaMultiModuleTask,
+            child: @Suppress("DEPRECATION") AbstractDokkaTask
         ): Provider<Directory> {
             val relativeProjectPath = parent.project.relativeProjectPath(child.project.path)
             val relativeFilePath = relativeProjectPath.replace(":", File.separator)
@@ -56,18 +60,12 @@ fun interface DokkaMultiModuleFileLayout {
     }
 }
 
-internal fun DokkaMultiModuleTask.targetChildOutputDirectory(
-    child: AbstractDokkaTask
+internal fun @Suppress("DEPRECATION") DokkaMultiModuleTask.targetChildOutputDirectory(
+    child: @Suppress("DEPRECATION") AbstractDokkaTask
 ): Provider<Directory> = fileLayout.get().targetChildOutputDirectory(this, child)
 
 
-internal fun DokkaMultiModuleTask.copyChildOutputDirectories() {
-    childDokkaTasks.forEach { child ->
-        this.copyChildOutputDirectory(child)
-    }
-}
-
-internal fun DokkaMultiModuleTask.copyChildOutputDirectory(child: AbstractDokkaTask) {
+internal fun @Suppress("DEPRECATION") DokkaMultiModuleTask.copyChildOutputDirectory(child: @Suppress("DEPRECATION") AbstractDokkaTask) {
     val targetChildOutputDirectory = project.file(fileLayout.get().targetChildOutputDirectory(this, child))
     val sourceChildOutputDirectory = child.outputDirectory.asFile.get()
 

dokka-runners/dokka-gradle-plugin/src/classicMain/kotlin/DokkaSourceSetMapper.kt

@@ -8,32 +8,33 @@ import org.jetbrains.dokka.*
 import org.jetbrains.dokka.DokkaConfiguration.ExternalDocumentationLink
 import java.io.File
 
-internal fun GradleDokkaSourceSetBuilder.toDokkaSourceSetImpl(): DokkaSourceSetImpl = DokkaSourceSetImpl(
-    classpath = classpath.toList(),
-    displayName = displayNameOrDefault(),
-    sourceSetID = sourceSetID,
-    sourceRoots = sourceRoots.toSet(),
-    dependentSourceSets = dependentSourceSets.get().toSet(),
-    samples = samples.toSet(),
-    includes = includes.toSet(),
-    includeNonPublic = includeNonPublic.get(),
-    documentedVisibilities = documentedVisibilities.get(),
-    reportUndocumented = reportUndocumented.get(),
-    skipEmptyPackages = skipEmptyPackages.get(),
-    skipDeprecated = skipDeprecated.get(),
-    jdkVersion = jdkVersion.get(),
-    sourceLinks = sourceLinks.get().build().toSet(),
-    perPackageOptions = perPackageOptions.get().build(),
-    externalDocumentationLinks = externalDocumentationLinksWithDefaults(),
-    languageVersion = languageVersion.orNull,
-    apiVersion = apiVersion.orNull,
-    noStdlibLink = noStdlibLink.get(),
-    noJdkLink = noJdkLink.get(),
-    suppressedFiles = suppressedFilesWithDefaults(),
-    analysisPlatform = platform.get()
-)
+internal fun @Suppress("DEPRECATION") GradleDokkaSourceSetBuilder.toDokkaSourceSetImpl(): DokkaSourceSetImpl =
+    DokkaSourceSetImpl(
+        classpath = classpath.toList(),
+        displayName = displayNameOrDefault(),
+        sourceSetID = sourceSetID,
+        sourceRoots = sourceRoots.toSet(),
+        dependentSourceSets = dependentSourceSets.get().toSet(),
+        samples = samples.toSet(),
+        includes = includes.toSet(),
+        includeNonPublic = includeNonPublic.get(),
+        documentedVisibilities = documentedVisibilities.get(),
+        reportUndocumented = reportUndocumented.get(),
+        skipEmptyPackages = skipEmptyPackages.get(),
+        skipDeprecated = skipDeprecated.get(),
+        jdkVersion = jdkVersion.get(),
+        sourceLinks = sourceLinks.get().build().toSet(),
+        perPackageOptions = perPackageOptions.get().build(),
+        externalDocumentationLinks = externalDocumentationLinksWithDefaults(),
+        languageVersion = languageVersion.orNull,
+        apiVersion = apiVersion.orNull,
+        noStdlibLink = noStdlibLink.get(),
+        noJdkLink = noJdkLink.get(),
+        suppressedFiles = suppressedFilesWithDefaults(),
+        analysisPlatform = platform.get()
+    )
 
-private fun GradleDokkaSourceSetBuilder.displayNameOrDefault(): String {
+private fun @Suppress("DEPRECATION") GradleDokkaSourceSetBuilder.displayNameOrDefault(): String {
     displayName.orNull?.let { return it }
     if (name.endsWith("Main") && name != "Main") {
         return name.removeSuffix("Main")
@@ -42,7 +43,7 @@ private fun GradleDokkaSourceSetBuilder.displayNameOrDefault(): String {
     return name
 }
 
-private fun GradleDokkaSourceSetBuilder.externalDocumentationLinksWithDefaults(): Set<ExternalDocumentationLinkImpl> {
+private fun @Suppress("DEPRECATION") GradleDokkaSourceSetBuilder.externalDocumentationLinksWithDefaults(): Set<ExternalDocumentationLinkImpl> {
     return externalDocumentationLinks.get().build()
         .run {
             if (noJdkLink.get()) this
@@ -61,7 +62,7 @@ private fun GradleDokkaSourceSetBuilder.externalDocumentationLinksWithDefaults()
         .toSet()
 }
 
-private fun GradleDokkaSourceSetBuilder.suppressedFilesWithDefaults(): Set<File> {
+private fun @Suppress("DEPRECATION") GradleDokkaSourceSetBuilder.suppressedFilesWithDefaults(): Set<File> {
     val suppressedGeneratedFiles = if (suppressGeneratedFiles.get()) {
         val generatedRoot = project.layout.buildDirectory.dir("generated").get().asFile
         sourceRoots