Add deprecated property to help migrate from JSON Dokka plugin config…

…uration (#3877)

docs/topics/dokka-migration.md

@@ -444,4 +444,4 @@ DGP v2 now supports Gradle build cache and configuration cache, improving build
 
 * Explore more [DGP v2 project examples](https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2). 
 * [Get started with Dokka](dokka-get-started.md).
-* [Learn more about Dokka plugins](dokka-plugins.md).
+* [Learn more about Dokka plugins](dokka-plugins.md).

dokka-runners/dokka-gradle-plugin/api/dokka-gradle-plugin.api

@@ -90,6 +90,7 @@ public abstract class org/jetbrains/dokka/gradle/DokkaExtension : java/io/Serial
 	public abstract fun getModulePath ()Lorg/gradle/api/provider/Property;
 	public abstract fun getModuleVersion ()Lorg/gradle/api/provider/Property;
 	public final fun getPluginsConfiguration ()Lorg/gradle/api/ExtensiblePolymorphicDomainObjectContainer;
+	public abstract fun getPluginsMapConfiguration ()Lorg/gradle/api/provider/MapProperty;
 	public abstract fun getSourceSetScopeDefault ()Lorg/gradle/api/provider/Property;
 	public abstract fun getSuppressInheritedMembers ()Lorg/gradle/api/provider/Property;
 	public abstract fun getSuppressObviousFunctions ()Lorg/gradle/api/provider/Property;

dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt

@@ -8,6 +8,7 @@ import org.gradle.api.file.DirectoryProperty
 import org.gradle.api.file.RegularFileProperty
 import org.gradle.api.model.ObjectFactory
 import org.gradle.api.plugins.ExtensionAware
+import org.gradle.api.provider.MapProperty
 import org.gradle.api.provider.Property
 import org.gradle.api.tasks.Nested
 import org.gradle.kotlin.dsl.newInstance
@@ -74,7 +75,7 @@ constructor(
      *
      * Each publication will generate one Dokka site based on the included Dokka Source Sets.
      *
-     * The type of site is determined by the Dokka Plugins. By default, an HTML site will be generated.
+     * The type of site is determined by the Dokka plugins. By default, an HTML site will be generated.
      */
     val dokkaPublications: NamedDomainObjectContainer<DokkaPublication> =
         extensions.adding(
@@ -213,5 +214,90 @@ constructor(
      */
     @Deprecated("Moved to DokkaPublication#suppressObviousFunctions")
     abstract val suppressObviousFunctions: Property<Boolean>
+
+    /**
+     * JSON configuration of Dokka plugins is deprecated.
+     * Typesafe configuration must be used instead - see [pluginsConfiguration].
+     *
+     * In DPGv1 the Dokka plugins could be configured by manually writing JSON.
+     * This caused issues with registering task inputs for Gradle up-to-date checks.
+     * (For more information on registering task inputs, see
+     * [Gradle Docs: Incremental build](https://docs.gradle.org/current/userguide/incremental_build.html)).
+     *
+     * In DGPv2 Dokka plugins must be configured in a typesafe way, using [pluginsConfiguration].
+     *
+     * #### Configuration of built-in Dokka plugins
+     *
+     * The built-in Dokka plugins can be configured using a typesafe DSL.
+     *
+     * This example demonstrates how to convert JSON configuration of the
+     * [Dokka Versioning plugin](https://kotl.in/dokka-versioning-plugin)
+     * into the new, typesafe config.
+     *
+     * ```
+     * // Deprecated configuration of the Dokka Versioning plugin:
+     * tasks.dokkaHtmlMultiModule {
+     *     pluginsMapConfiguration.set(
+     *         mapOf(
+     *             "org.jetbrains.dokka.versioning.VersioningPlugin" to """
+     *                 { "version": "1.2", "olderVersionsDir": "$projectDir/dokka-docs" }
+     *             """.trimIndent()
+     *         )
+     *     )
+     * }
+     *
+     * // New configuration in DGPv2 is typesafe and compatible with incremental builds.
+     * dokka {
+     *     pluginsConfiguration {
+     *         versioning {
+     *             version.set("1.2")
+     *             olderVersionsDir.set(projectDir.resolve("dokka-docs"))
+     *         }
+     *     }
+     * }
+     * ```
+     *
+     * #### External Dokka Plugin configuration
+     *
+     * To configure external Dokka plugins you must create a subclass of
+     * [DokkaPluginParametersBaseSpec][org.jetbrains.dokka.gradle.engine.plugins.DokkaPluginParametersBaseSpec],
+     * and register it as a configuration type using
+     * [pluginsConfiguration.registerBinding][org.gradle.api.ExtensiblePolymorphicDomainObjectContainer.registerBinding].
+     *
+     * ```
+     * import org.jetbrains.dokka.gradle.engine.plugins.DokkaPluginParametersBaseSpec
+     *
+     * @OptIn(DokkaInternalApi::class)
+     * abstract class MyCustomDokkaPluginConfiguration @Inject constructor(
+     *     name: String
+     * ) : DokkaPluginParametersBaseSpec(name, "demo.MyCustomDokkaPlugin") {
+     *
+     *     @get:Input
+     *     @get:Optional
+     *     abstract val flags: ListProperty<String>
+     *
+     *     override fun jsonEncode(): String {
+     *         // convert the 'flags' to JSON, to be decoded by MyCustomDokkaPlugin.
+     *     }
+     * }
+     *
+     * dokka {
+     *     pluginsConfiguration {
+     *         registerBinding(MyCustomDokkaPluginConfiguration::class, MyCustomDokkaPluginConfiguration::class)
+     *         register<MyCustomDokkaPluginConfiguration>("MyCustomDokkaPlugin") {
+     *             flags.add("someFlag...")
+     *         }
+     *     }
+     * }
+     * ```
+     *
+     * @see pluginsConfiguration
+     */
+    @Deprecated(
+        message = "JSON configuration of Dokka plugins is deprecated. Typesafe configuration must be used instead.",
+        level = DeprecationLevel.ERROR,
+    )
+    @Suppress("unused")
+    abstract val pluginsMapConfiguration: MapProperty<String, String>
     //endregion
 }