Add DokkaJavadocPlugin

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

@@ -506,6 +506,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 {

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)
 

dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/GradleTestKitUtils.kt

@@ -338,6 +338,7 @@ interface ProjectDirectoryScope {
  | )
  | filter {
  | includeGroup("org.jetbrains.dokka")
+ | includeGroup("org.jetbrains.dokka-javadoc")
  | }
  |}
  """.trimMargin()

dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/projects/MultiModuleProject.kt

@@ -38,6 +38,7 @@ fun TestScope.initMultiModuleProject(
  | // with ClassNotFound KotlinPluginExtension... very weird
  | kotlin("jvm") version embeddedKotlinVersion apply false
  | id("org.jetbrains.dokka") version "${DokkaConstants.DOKKA_VERSION}"
+ | id("org.jetbrains.dokka-javadoc") version "${DokkaConstants.DOKKA_VERSION}"
  |}
  |
  |dependencies {
@@ -52,6 +53,7 @@ fun TestScope.initMultiModuleProject(
  |plugins {
  | kotlin("jvm") version embeddedKotlinVersion
  | id("org.jetbrains.dokka") version "${DokkaConstants.DOKKA_VERSION}"
+ | id("org.jetbrains.dokka-javadoc") version "${DokkaConstants.DOKKA_VERSION}"
  |}
  |
  """.trimMargin()
@@ -79,6 +81,7 @@ fun TestScope.initMultiModuleProject(
  |plugins {
  | kotlin("jvm") version embeddedKotlinVersion
  | id("org.jetbrains.dokka") version "${DokkaConstants.DOKKA_VERSION}"
+ | id("org.jetbrains.dokka-javadoc") version "${DokkaConstants.DOKKA_VERSION}"
  |}
  |
  """.trimMargin()

dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/DokkaPluginFunctionalTest.kt

@@ -6,7 +6,6 @@ package org.jetbrains.dokka.gradle
 import io.kotest.assertions.asClue
 import io.kotest.assertions.withClue
 import io.kotest.core.spec.style.FunSpec
-import io.kotest.matchers.collections.shouldContainExactly
 import io.kotest.matchers.collections.shouldContainExactlyInAnyOrder
 import io.kotest.matchers.shouldBe
 import io.kotest.matchers.string.shouldContain
@@ -19,6 +18,7 @@ class DokkaPluginFunctionalTest : FunSpec({
  buildGradleKts = """
  |plugins {
  | id("org.jetbrains.dokka") version "$DOKKA_VERSION"
+ | id("org.jetbrains.dokka-javadoc") version "$DOKKA_VERSION"
  |}
  |
  |val printDeclarableConfigurations by tasks.registering {
@@ -45,9 +45,11 @@ class DokkaPluginFunctionalTest : FunSpec({
 
  dokkaTasks.shouldContainExactly(
  //@formatter:off
- "dokkaGenerate" to "Generates Dokka publications for all formats",
- "dokkaGenerateModuleHtml" to "Executes the Dokka Generator, generating a html module",
- "dokkaGeneratePublicationHtml" to "Executes the Dokka Generator, generating the html publication",
+ "dokkaGenerate" to "Generates Dokka publications for all formats",
+ "dokkaGenerateModuleHtml" to "Executes the Dokka Generator, generating a html module",
+ "dokkaGeneratePublicationHtml" to "Executes the Dokka Generator, generating the html publication",
+ "dokkaGenerateModuleJavadoc" to "Executes the Dokka Generator, generating a javadoc module",
+ "dokkaGeneratePublicationJavadoc" to "Executes the Dokka Generator, generating the javadoc publication",
  //@formatter:on
  )
  }
@@ -70,13 +72,17 @@ class DokkaPluginFunctionalTest : FunSpec({
  .map { it.trim() }
  .sorted()
 
- declarableConfigurations.shouldContainExactly(
- "dokka",
- "dokkaHtmlGeneratorRuntime",
- "dokkaHtmlPlugin",
- "dokkaHtmlPublicationPlugin",
- "dokkaHtmlPublicationPluginApiOnly~internal",
- "dokkaPlugin",
+ declarableConfigurations.shouldContainExactlyInAnyOrder(
+ buildList {
+ add("dokka")
+ add("dokkaPlugin")
+ expectedFormats.forEach {
+ add("dokka${it}GeneratorRuntime")
+ add("dokka${it}Plugin")
+ add("dokka${it}PublicationPlugin")
+ add("dokka${it}PublicationPluginApiOnly~internal")
+ }
+ }
  )
  }
  }
@@ -223,10 +229,8 @@ class DokkaPluginFunctionalTest : FunSpec({
  * The output formats that Dokka supports.
  */
  private val expectedFormats = listOf(
- //"Gfm",
  "Html",
- //"Javadoc",
- //"Jekyll",
+ "Javadoc",
  )
 
  /**
@@ -284,6 +288,5 @@ class DokkaPluginFunctionalTest : FunSpec({
  .filterNot { it.startsWith("Consumable configurations with identical capabilities within a project") }
  .joinToString("\n")
  }
-
  }
 }

dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/MultiModuleFunctionalTest.kt

@@ -32,6 +32,7 @@ class MultiModuleFunctionalTest : FunSpec({
  project.runner
  .addArguments(
  ":dokkaGenerate",
+ "--stacktrace",
  "--rerun-tasks",
  )
  .forwardOutput()
@@ -145,7 +146,7 @@ class MultiModuleFunctionalTest : FunSpec({
  test("expect build is successful") {
  output shouldContainAll listOf(
  "BUILD SUCCESSFUL",
- "4 actionable tasks: 4 up-to-date",
+ "8 actionable tasks: 8 up-to-date",
  )
  }
 
@@ -189,6 +190,9 @@ class MultiModuleFunctionalTest : FunSpec({
  ":dokkaGeneratePublicationHtml",
  ":subproject-hello:dokkaGenerateModuleHtml",
  ":subproject-goodbye:dokkaGenerateModuleHtml",
+ ":dokkaGeneratePublicationJavadoc",
+ ":subproject-hello:dokkaGenerateModuleJavadoc",
+ ":subproject-goodbye:dokkaGenerateModuleJavadoc",
  )
 
  test("setup build cache") {
@@ -215,6 +219,7 @@ class MultiModuleFunctionalTest : FunSpec({
  .addArguments(
  "clean",
  "--build-cache",
+ "--stacktrace",
  )
  .forwardOutput()
  .build {
@@ -248,6 +253,7 @@ class MultiModuleFunctionalTest : FunSpec({
  .addArguments(
  "clean",
  "--build-cache",
+ "--stacktrace",
  )
  .forwardOutput()
  .build {
@@ -445,6 +451,7 @@ class MultiModuleFunctionalTest : FunSpec({
  "--no-configuration-cache",
  "--no-build-cache",
  "--quiet",
+ "--stacktrace",
  )
  .forwardOutput()
  .build {
@@ -460,6 +467,7 @@ class MultiModuleFunctionalTest : FunSpec({
  "--no-configuration-cache",
  "--no-build-cache",
  "--no-parallel",
+ "--stacktrace",
  // no logging option => lifecycle log level
  )
  .forwardOutput()
@@ -480,13 +488,22 @@ class MultiModuleFunctionalTest : FunSpec({
  .filter { it.startsWith("> Task :") }
  .shouldContainAll(
  "> Task :clean",
- "> Task :dokkaGenerate",
- "> Task :dokkaGenerateModuleHtml",
- "> Task :dokkaGeneratePublicationHtml",
  "> Task :subproject-goodbye:clean",
- "> Task :subproject-goodbye:dokkaGenerateModuleHtml",
  "> Task :subproject-hello:clean",
+
+ "> Task :dokkaGenerate",
+
+ "> Task :dokkaGeneratePublicationHtml",
+ "> Task :dokkaGeneratePublicationJavadoc",
+
+ "> Task :dokkaGenerateModuleHtml",
+ "> Task :dokkaGenerateModuleJavadoc",
+
  "> Task :subproject-hello:dokkaGenerateModuleHtml",
+ "> Task :subproject-hello:dokkaGenerateModuleJavadoc",
+
+ "> Task :subproject-goodbye:dokkaGenerateModuleHtml",
+ "> Task :subproject-goodbye:dokkaGenerateModuleJavadoc",
  )
  }
  }
@@ -580,6 +597,7 @@ class MultiModuleFunctionalTest : FunSpec({
  .addArguments(
  ":dokkaGeneratePublicationHtml",
  "--rerun-tasks",
+ "--stacktrace",
  )
  .forwardOutput()
  .build {