Merge branch 'master' into adam/feat/KT-70336/rationalise-plugin-mode…

…-flags

# Conflicts:
#	dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/KotlinDslAccessorsTest.kt

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

@@ -80,6 +80,7 @@ public abstract class org/jetbrains/dokka/gradle/DokkaExtension : java/io/Serial
 	public final fun ProcessIsolation (Lkotlin/jvm/functions/Function1;)Lorg/jetbrains/dokka/gradle/workers/WorkerIsolation$Process;
 	public static synthetic fun ProcessIsolation$default (Lorg/jetbrains/dokka/gradle/DokkaExtension;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lorg/jetbrains/dokka/gradle/workers/WorkerIsolation$Process;
 	public abstract fun getDokkaCacheDirectory ()Lorg/gradle/api/file/DirectoryProperty;
+	public abstract fun getDokkaEngineVersion ()Lorg/gradle/api/provider/Property;
 	public abstract fun getDokkaGeneratorIsolation ()Lorg/gradle/api/provider/Property;
 	public abstract fun getDokkaModuleDirectory ()Lorg/gradle/api/file/DirectoryProperty;
 	public abstract fun getDokkaPublicationDirectory ()Lorg/gradle/api/file/DirectoryProperty;
@@ -90,19 +91,6 @@ public abstract class org/jetbrains/dokka/gradle/DokkaExtension : java/io/Serial
 	public abstract fun getModuleVersion ()Lorg/gradle/api/provider/Property;
 	public final fun getPluginsConfiguration ()Lorg/gradle/api/ExtensiblePolymorphicDomainObjectContainer;
 	public abstract fun getSourceSetScopeDefault ()Lorg/gradle/api/provider/Property;
-	public final fun getVersions ()Lorg/jetbrains/dokka/gradle/DokkaExtension$Versions;
-}
-
-public abstract interface class org/jetbrains/dokka/gradle/DokkaExtension$Versions : org/gradle/api/plugins/ExtensionAware {
-	public static final field Companion Lorg/jetbrains/dokka/gradle/DokkaExtension$Versions$Companion;
-	public abstract fun getFreemarker ()Lorg/gradle/api/provider/Property;
-	public abstract fun getJetbrainsDokka ()Lorg/gradle/api/provider/Property;
-	public abstract fun getJetbrainsMarkdown ()Lorg/gradle/api/provider/Property;
-	public abstract fun getKotlinxCoroutines ()Lorg/gradle/api/provider/Property;
-	public abstract fun getKotlinxHtml ()Lorg/gradle/api/provider/Property;
-}
-
-public final class org/jetbrains/dokka/gradle/DokkaExtension$Versions$Companion {
 }
 
 public abstract interface class org/jetbrains/dokka/gradle/DokkaMultiModuleFileLayout {
@@ -506,6 +494,10 @@ public final class org/jetbrains/dokka/gradle/formats/DokkaHtmlPlugin$inlined$sa
 	public final synthetic fun execute (Ljava/lang/Object;)V
 }
 
+public abstract class org/jetbrains/dokka/gradle/formats/DokkaJavadocPlugin : org/jetbrains/dokka/gradle/formats/DokkaFormatPlugin {
+	public fun configure (Lorg/jetbrains/dokka/gradle/formats/DokkaFormatPlugin$DokkaFormatPluginContext;)V
+}
+
 public abstract class org/jetbrains/dokka/gradle/formats/DokkaPublication : java/io/Serializable, org/gradle/api/Named, org/gradle/api/plugins/ExtensionAware {
 	public abstract fun getCacheRoot ()Lorg/gradle/api/file/DirectoryProperty;
 	public abstract fun getEnabled ()Lorg/gradle/api/provider/Property;

dokka-runners/dokka-gradle-plugin/build.gradle.kts

@@ -98,22 +98,46 @@ dependencies {
 }
 
 gradlePlugin {
-    plugins.register("dokka") {
-        id = "org.jetbrains.dokka"
-        displayName = "Dokka Gradle Plugin"
-        description = "Dokka is an API documentation engine for Kotlin"
-        implementationClass = "org.jetbrains.dokka.gradle.DokkaPlugin"
+    plugins.configureEach {
         tags.addAll(
             "dokka",
             "kotlin",
             "kdoc",
             "android",
             "api reference",
             "documentation",
-            "html",
-            "website",
         )
     }
+    plugins.register("dokkaHtml") {
+        id = "org.jetbrains.dokka"
+        displayName = "Dokka Gradle Plugin"
+        description = """
+            Dokka is the API documentation engine for Kotlin.
+            
+            This plugin generates output that looks like Javadoc websites.
+            See https://kotlinlang.org/docs/dokka-html.html for more information.
+            
+            HTML is Dokka's default and recommended output format. It is currently in Beta and approaching the Stable release.
+            """.trimIndent()
+        implementationClass = "org.jetbrains.dokka.gradle.DokkaPlugin"
+        tags.addAll("html")
+    }
+    plugins.register("dokkaJavadoc") {
+        id = "org.jetbrains.dokka-javadoc"
+        displayName = "Dokka Gradle Plugin Javadoc"
+        description = """
+            Dokka is the API documentation engine for Kotlin.
+            
+            This plugin generates output that looks like Javadoc websites.
+            See https://kotlinlang.org/docs/dokka-javadoc.html for more information.
+            
+            The Javadoc output format is still in Alpha, so you may find bugs and experience migration issues when using it.
+            Successful integration with tools that accept Java's Javadoc HTML as input is not guaranteed.
+            You use it at your own risk.
+            """.trimIndent()
+        implementationClass = "org.jetbrains.dokka.gradle.formats.DokkaJavadocPlugin"
+        tags.addAll("javadoc")
+    }
 }
 
 testing.suites {
@@ -189,10 +213,6 @@ apiValidation {
 val generateDokkaGradlePluginConstants by tasks.registering(GenerateDokkaGradlePluginConstants::class) {
     val dokkaPluginConstants = objects.mapProperty<String, String>().apply {
         put("DOKKA_VERSION", project.version.toString())
-        put("DOKKA_DEPENDENCY_VERSION_KOTLINX_HTML", libs.versions.kotlinx.html)
-        put("DOKKA_DEPENDENCY_VERSION_KOTLINX_COROUTINES", libs.versions.kotlinx.coroutines)
-        put("DOKKA_DEPENDENCY_VERSION_FREEMARKER", libs.versions.freemarker)
-        put("DOKKA_DEPENDENCY_VERSION_JETBRAINS_MARKDOWN", libs.versions.jetbrains.markdown)
     }
 
     properties.set(dokkaPluginConstants)

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

@@ -104,14 +104,8 @@ constructor(
             dokkaModuleDirectory.convention(layout.buildDirectory.dir("dokka-module"))
 //            @Suppress("DEPRECATION")
 //            dokkaConfigurationsDirectory.convention(layout.buildDirectory.dir("dokka-config"))
-        }
 
-        dokkaExtension.versions {
-            jetbrainsDokka.convention(DokkaConstants.DOKKA_VERSION)
-            jetbrainsMarkdown.convention(DokkaConstants.DOKKA_DEPENDENCY_VERSION_JETBRAINS_MARKDOWN)
-            freemarker.convention(DokkaConstants.DOKKA_DEPENDENCY_VERSION_FREEMARKER)
-            kotlinxHtml.convention(DokkaConstants.DOKKA_DEPENDENCY_VERSION_KOTLINX_HTML)
-            kotlinxCoroutines.convention(DokkaConstants.DOKKA_DEPENDENCY_VERSION_KOTLINX_COROUTINES)
+            dokkaEngineVersion.convention(DokkaConstants.DOKKA_VERSION)
         }
 
         dokkaExtension.dokkaGeneratorIsolation.convention(
@@ -214,6 +208,7 @@ constructor(
                 suppress.convention(false)
                 skipDeprecated.convention(false)
                 reportUndocumented.convention(false)
+                documentedVisibilities.convention(listOf(VisibilityModifier.Public))
             }
 
             externalDocumentationLinks {

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

@@ -122,24 +122,12 @@ constructor(
         extensions.adding("pluginsConfiguration", objects.dokkaPluginParametersContainer())
 
     /**
-     * Versions of dependencies that Dokka Gradle Plugin will use to run Dokka Generator.
+     * The default version of Dokka dependencies that are used at runtime during generation.
      *
-     * These versions can be set to change the versions of dependencies that Dokka Gradle Plugin uses by default,
-     * or can be read to align versions.
+     * This value defaults to the current Dokka Gradle Plugin version, but can be overridden
+     * if you want to use a newer or older version of Dokka at runtime.
      */
-    val versions: Versions = extensions.adding("versions", objects.newInstance())
-
-    interface Versions : ExtensionAware {
-
-        /** Default version used for Dokka dependencies */
-        val jetbrainsDokka: Property<String>
-        val jetbrainsMarkdown: Property<String>
-        val freemarker: Property<String>
-        val kotlinxHtml: Property<String>
-        val kotlinxCoroutines: Property<String>
-
-        companion object
-    }
+    abstract val dokkaEngineVersion: Property<String>
 
     /**
      * Dokka Gradle Plugin runs Dokka Generator in a separate

dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaPackageOptionsSpec.kt

@@ -1,5 +1,3 @@
-@file:Suppress("FunctionName")
-
 /*
  * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
@@ -20,6 +18,7 @@ import java.io.Serializable
  * ```kotlin
  * tasks.dokkaHtml {
  *     dokkaSourceSets.configureEach {
+ *         // create a new perPackageOption
  *         perPackageOption {
  *             matchingRegex.set(".*internal.*")
  *             suppress.set(true)

dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceSetSpec.kt

@@ -214,9 +214,11 @@ constructor(
     abstract val sourceLinks: DomainObjectSet<DokkaSourceLinkSpec>
 
     /**
-     * Allows to customize documentation generation options on a per-package basis.
+     * Allows customising documentation generation options on a per-package basis.
      *
-     * @see DokkaPackageOptionsSpec for details
+     * Use the [perPackageOptions] function to add a new item.
+     *
+     * @see DokkaPackageOptionsSpec
      */
     @get:Nested
     abstract val perPackageOptions: DomainObjectSet<DokkaPackageOptionsSpec>

dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaFormatPlugin.kt

@@ -15,7 +15,6 @@ import org.gradle.api.file.FileSystemOperations
 import org.gradle.api.file.ProjectLayout
 import org.gradle.api.logging.Logging
 import org.gradle.api.model.ObjectFactory
-import org.gradle.api.provider.Property
 import org.gradle.api.provider.Provider
 import org.gradle.api.provider.ProviderFactory
 import org.gradle.kotlin.dsl.*
@@ -134,8 +133,9 @@ abstract class DokkaFormatPlugin(
                     // https://github.com/gradle/gradle/issues/27435)
                     dependenciesContainer.resolutionStrategy.eachDependency {
                         if (requested.group == "org.jetbrains.dokka" && requested.version.isNullOrBlank()) {
-                            logger.info("adding version of dokka dependency '$requested'")
-                            useVersion(dokkaExtension.versions.jetbrainsDokka.get())
+                            val dokkaVersion = dokkaExtension.dokkaEngineVersion.get()
+                            logger.info("[${context.project.path}] adding Dokka version $dokkaVersion to dependency '$requested'")
+                            useVersion(dokkaVersion)
                         }
                     }
                 }
@@ -164,7 +164,7 @@ abstract class DokkaFormatPlugin(
 
         /** Create a [Dependency] for a Dokka module */
         fun DependencyHandler.dokka(module: String): Provider<Dependency> =
-            dokkaExtension.versions.jetbrainsDokka.map { version -> create("org.jetbrains.dokka:$module:$version") }
+            dokkaExtension.dokkaEngineVersion.map { version -> create("org.jetbrains.dokka:$module:$version") }
 
         private fun AttributeContainer.dokkaPluginsClasspath() {
             attribute(DokkaFormatAttribute, formatDependencies.formatAttributes.format.name)
@@ -211,27 +211,17 @@ abstract class DokkaFormatPlugin(
 
     private fun DokkaFormatPluginContext.addDefaultDokkaDependencies() {
         project.dependencies {
-            /** lazily create a [Dependency] with the provided [version] */
-            infix fun String.version(version: Property<String>): Provider<Dependency> =
-                version.map { v -> create("$this:$v") }
-
-            with(dokkaExtension.versions) {
-                dokkaPlugin(dokka("templating-plugin"))
-                dokkaPlugin(dokka("dokka-base"))
-
-                dokkaGenerator(
-                    if (project.pluginFeaturesService.enableK2Analysis) {
-                        dokka("analysis-kotlin-symbols") // K2 analysis
-                    } else {
-                        dokka("analysis-kotlin-descriptors") // K1 analysis
-                    }
-                )
-                dokkaGenerator(dokka("dokka-core"))
-                dokkaGenerator("org.freemarker:freemarker" version freemarker)
-                dokkaGenerator("org.jetbrains:markdown" version jetbrainsMarkdown)
-                dokkaGenerator("org.jetbrains.kotlinx:kotlinx-coroutines-core" version kotlinxCoroutines)
-                dokkaGenerator("org.jetbrains.kotlinx:kotlinx-html" version kotlinxHtml)
-            }
+            dokkaPlugin(dokka("templating-plugin"))
+            dokkaPlugin(dokka("dokka-base"))
+
+            dokkaGenerator(
+                if (project.pluginFeaturesService.enableK2Analysis) {
+                    dokka("analysis-kotlin-symbols") // K2 analysis
+                } else {
+                    dokka("analysis-kotlin-descriptors") // K1 analysis
+                }
+            )
+            dokkaGenerator(dokka("dokka-core"))
         }
     }
 

dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaHtmlPlugin.kt

@@ -104,10 +104,9 @@ constructor(
 
         formatDependencies.dokkaPublicationPluginClasspathApiOnly
             .dependencies
-            .addLater(dokkaExtension.versions.jetbrainsDokka.map { v ->
+            .addLater(dokkaExtension.dokkaEngineVersion.map { v ->
                 project.dependencies.create("org.jetbrains.dokka:all-modules-page-plugin:$v")
             })
-
     }
 
     /**

dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaJavadocPlugin.kt

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+package org.jetbrains.dokka.gradle.formats
+
+import org.gradle.kotlin.dsl.dependencies
+import org.jetbrains.dokka.gradle.internal.DokkaInternalApi
+
+/**
+ * Gradle plugin that configures Dokka Javadoc output format
+ */
+abstract class DokkaJavadocPlugin
+@DokkaInternalApi
+constructor() : DokkaFormatPlugin(formatName = "javadoc") {
+    override fun DokkaFormatPluginContext.configure() {
+        project.dependencies {
+            dokkaPlugin(dokka("javadoc-plugin"))
+        }
+    }
+}

dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/v2MigrationUtils.kt

@@ -28,7 +28,7 @@ internal fun addV2MigrationHelpers(
     project.configurations.createDokkaDefaultRuntimeConfiguration()
 
     setupDokkaTasks(project, "GFM")
-    setupDokkaTasks(project, "Javadoc", multiModuleTaskSupported = false)
+    setupDokkaTasks(project, "Javadoc", createDokkaPluginFormatConfiguration = false, multiModuleTaskSupported = false)
     setupDokkaTasks(project, "Jekyll")
     setupDokkaTasks(project, "HTML", createDokkaPluginFormatConfiguration = false)
 
@@ -63,11 +63,9 @@ private fun setupDokkaTasks(
 
     /** @see org.jetbrains.dokka.gradle.maybeCreateDokkaPluginConfiguration */
     fun ConfigurationContainer.createDokkaPluginConfiguration(taskName: String) {
-        if (createDokkaPluginFormatConfiguration) {
-            create("${taskName}Plugin") {
-                declarable()
-                deprecate(replaceWith = newConfs.pluginsClasspath)
-            }
+        create("${taskName}Plugin") {
+            declarable()
+            deprecate(replaceWith = newConfs.pluginsClasspath)
         }
     }
 
@@ -79,8 +77,11 @@ private fun setupDokkaTasks(
         }
     }
 
-    project.configurations.createDokkaPluginConfiguration(taskName = baseTaskName)
-    project.configurations.createDokkaRuntimeConfiguration(taskName = baseTaskName)
+    if (createDokkaPluginFormatConfiguration) {
+        // Don't create dokka${Format}Plugin Configurations, v2 will create Configurations with the same name and purpose.
+        project.configurations.createDokkaPluginConfiguration(taskName = baseTaskName)
+        project.configurations.createDokkaRuntimeConfiguration(taskName = baseTaskName)
+    }
 
     project.tasks.register<DokkaTask>(baseTaskName) {
         description = "$taskDesc Generates documentation in '$format' format."
@@ -119,7 +120,7 @@ private fun ConfigurationContainer.createDokkaDefaultRuntimeConfiguration(): Con
     return create("dokkaRuntime") {
         description = "[⚠ V1 Configurations are disabled] Classpath used to execute the Dokka Generator."
         declarable()
-        deprecate(DependencyContainerNames("html").generatorClasspath)
+        deprecate(DependencyContainerNames("").generatorClasspath)
     }
 }