Add DokkaJavadocPlugin (#3796)

* Add DokkaJavadocPlugin KT-71357
Kotlin · Sep 11, 2024 · d5515e9 · d5515e9
1 parent e8bc8fa
commit d5515e9
Show file tree

Hide file tree

Showing 8 changed files with 101 additions and 28 deletions.
diff --git a/dokka-runners/dokka-gradle-plugin/api/dokka-gradle-plugin.api b/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;

diff --git a/dokka-runners/dokka-gradle-plugin/build.gradle.kts b/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 {

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaJavadocPlugin.kt b/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"))
+        }
+    }
+}
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/v2MigrationUtils.kt b/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)
 

diff --git a/dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/GradleTestKitUtils.kt b/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()

diff --git a/dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/projects/MultiModuleProject.kt b/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()

diff --git a/dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/DokkaPluginFunctionalTest.kt b/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")
         }
-
     }
 }
diff --git a/dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/MultiModuleFunctionalTest.kt b/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 {