Merge pull request #11 from javalin/build/dokka-javadoc

Render the javadoc jar with Dokka

Author: 7agustibm

CHANGELOG.md

@@ -74,6 +74,8 @@ is a breaking change; the README has a
   incompatible major, and it requested a `renderExample.js` that does not exist.
 - Building the plugin without registering a package now fails saying so, instead of scanning
   the package `kotlin.Unit`, which is a class and matches nothing.
+- The published `javadoc` jar contained nothing but a manifest, because it was built from the
+  `javadoc` task and every source file is Kotlin. It is now rendered by Dokka.
 
 Set the date and add the release link below when the `v7.0.0` tag is cut.
 

build.gradle.kts

@@ -4,6 +4,8 @@ plugins {
     `maven-publish`
     kotlin("jvm") version "2.2.20"
     id("io.gitlab.arturbosch.detekt") version "1.23.8"
+    id("org.jetbrains.dokka") version "2.2.0"
+    id("org.jetbrains.dokka-javadoc") version "2.2.0"
 }
 
 detekt {
@@ -27,6 +29,23 @@ repositories {
     mavenCentral()
 }
 
+java {
+    withJavadocJar()
+    withSourcesJar()
+}
+
+// `withJavadocJar()` fills the jar from the `javadoc` task, which has no Java source to read
+// here, so what shipped was 261 bytes containing nothing but a manifest. Dokka renders the KDoc
+// instead — the API this artifact documents is Kotlin.
+//
+// The jar is redirected rather than replaced by one of our own: `withJavadocJar()` is also what
+// registers the `javadocElements` variant, so a consumer resolving through Gradle module
+// metadata still finds the documentation. Declaring a separate task would publish the jar to
+// Maven and leave that variant missing.
+tasks.named<Jar>("javadocJar") {
+    from(tasks.dokkaGeneratePublicationJavadoc)
+}
+
 publishing {
     publications {
         create<MavenPublication>("library") {
@@ -93,11 +112,6 @@ tasks.withType<JavaCompile>().configureEach {
     options.release.set(17)
 }
 
-java {
-    withJavadocJar()
-    withSourcesJar()
-}
-
 dependencies {
     // All of these appear in this plugin's public API, so they belong on the consumer's
     // compile classpath: Javalin's Context and WsMessageContext in the builder and the