Javadocs (#347)

* Reorganize the project in convention scripts

* Managed to get the aggregated javadocs

* Dokka now works!

admin-client/build.gradle.kts

@@ -3,6 +3,7 @@ import org.openapitools.generator.gradle.plugin.tasks.GenerateTask
 
 plugins {
   `java-library`
+  `java-conventions`
   id("org.openapi.generator") version "7.5.0"
   `library-publishing-conventions`
 }

build.gradle.kts

@@ -1,15 +1,28 @@
-import net.ltgt.gradle.errorprone.errorprone
-
 plugins {
-  java
-  kotlin("jvm") version "2.0.0" apply false
-  kotlin("plugin.serialization") version "2.0.0" apply false
-
-  id("net.ltgt.errorprone") version "3.0.1"
   id("com.github.jk1.dependency-license-report") version "2.0"
   id("io.github.gradle-nexus.publish-plugin") version "1.3.0"
 
-  alias(pluginLibs.plugins.spotless)
+  id("org.jetbrains.dokka") version "1.9.20"
+
+  // https://github.com/gradle/gradle/issues/20084#issuecomment-1060822638
+  id(pluginLibs.plugins.spotless.get().pluginId) apply false
+}
+
+// Dokka is bringing in jackson unshaded and it's messing up other plugins, so we override those
+// here!
+buildscript {
+  dependencies {
+    classpath("com.fasterxml.jackson.core:jackson-core:2.17.1")
+    classpath("com.fasterxml.jackson.core:jackson-databind:2.17.1")
+    classpath("com.fasterxml.jackson.dataformat:jackson-dataformat-xml:2.17.1")
+    classpath("com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.17.1")
+    classpath("com.fasterxml.jackson.module:jackson-module-kotlin:2.17.1")
+    classpath("org.jetbrains.dokka:dokka-gradle-plugin:1.9.20") {
+      exclude("com.fasterxml.jackson")
+      exclude("com.fasterxml.jackson.dataformat")
+      exclude("com.fasterxml.jackson.module")
+    }
+  }
 }
 
 val protobufVersion = coreLibs.versions.protobuf.get()
@@ -23,32 +36,6 @@ allprojects {
   version = restateVersion
 
   configure<com.diffplug.gradle.spotless.SpotlessExtension> {
-    java {
-      targetExclude("build/**/*.java")
-
-      googleJavaFormat()
-
-      licenseHeaderFile("$rootDir/config/license-header")
-    }
-
-    format("proto") {
-      target("**/*.proto")
-
-      // Exclude proto and service-protocol directories because those get the license header from
-      // their repos.
-      targetExclude(
-          fileTree("$rootDir/sdk-common/src/main/proto") { include("**/*.*") },
-          fileTree("$rootDir/sdk-core/src/main/service-protocol") { include("**/*.*") })
-
-      licenseHeaderFile("$rootDir/config/license-header", "syntax")
-    }
-
-    kotlin {
-      targetExclude("build/generated/**/*.kt")
-      ktfmt()
-      licenseHeaderFile("$rootDir/config/license-header")
-    }
-
     kotlinGradle { ktfmt() }
 
     format("properties") {
@@ -57,7 +44,7 @@ allprojects {
     }
   }
 
-  tasks { check { dependsOn(checkLicense) } }
+  tasks.named("check") { dependsOn("checkLicense") }
 
   licenseReport {
     renderers = arrayOf(com.github.jk1.license.render.CsvReportRenderer())
@@ -82,34 +69,13 @@ allprojects {
   }
 }
 
-subprojects {
-  apply(plugin = "java")
-  apply(plugin = "net.ltgt.errorprone")
-
-  dependencies { errorprone("com.google.errorprone:error_prone_core:2.13.1") }
-
-  // Configure the java toolchain to use. If not found, it will be downloaded automatically
-  java {
-    toolchain { languageVersion = JavaLanguageVersion.of(11) }
-
-    withJavadocJar()
-    withSourcesJar()
-  }
-
-  tasks.withType<JavaCompile>().configureEach {
-    options.errorprone.disableWarningsInGeneratedCode.set(true)
-    options.errorprone.disable(
-        // We use toString() in proto messages for debugging reasons.
-        "LiteProtoToString",
-        // This check is proposing to use a guava API instead...
-        "StringSplitter",
-        // This is conflicting with a javadoc warn lint
-        "MissingSummary")
-    options.errorprone.excludedPaths.set(".*/build/generated/.*")
-  }
-
-  tasks.withType<Test> { useJUnitPlatform() }
-}
+// Dokka configuration
+subprojects
+    .filter {
+      !setOf("sdk-api", "sdk-api-gen", "examples", "sdk-aggregated-javadocs", "admin-client")
+          .contains(it.name)
+    }
+    .forEach { p -> p.plugins.apply("org.jetbrains.dokka") }
 
 nexusPublishing {
   repositories {

buildSrc/build.gradle.kts

@@ -4,4 +4,13 @@ plugins {
 
 repositories {
     mavenCentral()
+    gradlePluginPortal()
 }
+
+
+dependencies {
+    implementation("net.ltgt.gradle:gradle-errorprone-plugin:4.0.0")
+    implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:2.0.0")
+    implementation("org.jetbrains.kotlin:kotlin-serialization:2.0.0")
+    implementation("com.diffplug.spotless:spotless-plugin-gradle:6.25.0")
+}

buildSrc/src/main/kotlin/java-conventions.gradle.kts

@@ -0,0 +1,43 @@
+
+import net.ltgt.gradle.errorprone.errorprone
+
+plugins {
+    java
+    id("net.ltgt.errorprone")
+    id("com.diffplug.spotless")
+}
+
+dependencies { errorprone("com.google.errorprone:error_prone_core:2.28.0") }
+
+// Configure the java toolchain to use. If not found, it will be downloaded automatically
+java {
+    toolchain { languageVersion = JavaLanguageVersion.of(11) }
+
+    withJavadocJar()
+    withSourcesJar()
+}
+
+tasks.withType<JavaCompile>().configureEach {
+    options.errorprone.disableWarningsInGeneratedCode.set(true)
+    options.errorprone.disable(
+        // We use toString() in proto messages for debugging reasons.
+        "LiteProtoToString",
+        // This check is proposing to use a guava API instead...
+        "StringSplitter",
+        // This is conflicting with a javadoc warn lint
+        "MissingSummary"
+    )
+    options.errorprone.excludedPaths.set(".*/build/generated/.*")
+}
+
+tasks.withType<Test> { useJUnitPlatform() }
+
+configure<com.diffplug.gradle.spotless.SpotlessExtension> {
+    java {
+        targetExclude("build/**/*.java")
+
+        googleJavaFormat()
+
+        licenseHeaderFile("$rootDir/config/license-header")
+    }
+}

buildSrc/src/main/kotlin/kotlin-conventions.gradle.kts

@@ -0,0 +1,19 @@
+plugins {
+    kotlin("jvm")
+    kotlin("plugin.serialization")
+    id("com.diffplug.spotless")
+}
+
+kotlin {
+    jvmToolchain(11)
+}
+
+tasks.withType<Test> { useJUnitPlatform() }
+
+configure<com.diffplug.gradle.spotless.SpotlessExtension> {
+    kotlin {
+        targetExclude("build/generated/**/*.kt")
+        ktfmt()
+        licenseHeaderFile("$rootDir/config/license-header")
+    }
+}

buildSrc/src/main/kotlin/test-jar-conventions.gradle.kts

@@ -0,0 +1,9 @@
+configurations { register("testArchive") }
+
+tasks.register<Jar>("testJar") {
+    archiveClassifier.set("tests")
+
+    from(project.the<SourceSetContainer>()["test"].output)
+}
+
+artifacts { add("testArchive", tasks["testJar"]) }

examples/build.gradle.kts

@@ -2,11 +2,10 @@ import com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar
 import com.github.jengelman.gradle.plugins.shadow.transformers.ServiceFileTransformer
 
 plugins {
-  java
-  kotlin("jvm")
-  kotlin("plugin.serialization")
-  application
+  `java-conventions`
+  `kotlin-conventions`
   alias(kotlinLibs.plugins.ksp)
+  application
   id("com.github.johnrengelman.shadow").version("8.1.1")
 }
 
@@ -28,6 +27,8 @@ dependencies {
   implementation(kotlinLibs.kotlinx.serialization.json)
 
   implementation(coreLibs.log4j.core)
+  implementation(platform(vertxLibs.vertx.bom))
+  implementation(vertxLibs.vertx.core)
 }
 
 application {

examples/src/main/kotlin/my/restate/sdk/examples/CounterKt.kt

@@ -12,9 +12,13 @@ import dev.restate.sdk.annotation.Handler
 import dev.restate.sdk.annotation.Shared
 import dev.restate.sdk.annotation.VirtualObject
 import dev.restate.sdk.http.vertx.RestateHttpEndpointBuilder
+import dev.restate.sdk.kotlin.HandlerRunner
 import dev.restate.sdk.kotlin.KtStateKey
 import dev.restate.sdk.kotlin.ObjectContext
 import dev.restate.sdk.kotlin.SharedObjectContext
+import io.vertx.core.Vertx
+import io.vertx.core.VertxOptions
+import kotlinx.coroutines.Dispatchers
 import kotlinx.serialization.Serializable
 import org.apache.logging.log4j.LogManager
 import org.apache.logging.log4j.Logger
@@ -58,5 +62,9 @@ class CounterKt {
 }
 
 fun main() {
-  RestateHttpEndpointBuilder.builder().bind(CounterKt()).buildAndListen()
+  RestateHttpEndpointBuilder.builder(Vertx.vertx(VertxOptions().setEventLoopPoolSize(8)))
+      .bind(
+          CounterKtServiceDefinitionFactory().create(CounterKt()),
+          HandlerRunner.Options(Dispatchers.Unconfined))
+      .buildAndListen()
 }

examples/src/main/resources/log4j2.properties

@@ -17,10 +17,10 @@ appender.console.filter.replay.0.value = REPLAYING
 
 # Restate logs to debug level
 logger.app.name = dev.restate
-logger.app.level = info
+logger.app.level = error
 logger.app.additivity = false
 logger.app.appenderRef.console.ref = consoleLogger
 
 # Root logger
-rootLogger.level = info
+rootLogger.level = error
 rootLogger.appenderRef.stdout.ref = consoleLogger

sdk-aggregated-javadocs/build.gradle.kts

@@ -0,0 +1,17 @@
+plugins { id("io.freefair.aggregate-javadoc") version "8.6" }
+
+rootProject.subprojects
+    .filter { it.name != "examples" }
+    .forEach {
+      it.plugins.withId("java") {
+        // Add dependency
+        dependencies.javadoc(it)
+
+        tasks.javadoc { classpath += it.configurations["compileClasspath"] }
+      }
+    }
+
+tasks.javadoc {
+  title = "Restate SDK-Java documentation"
+  options.windowTitle = "Restate SDK-Java documentation"
+}

sdk-api-gen-common/build.gradle.kts

@@ -1,4 +1,5 @@
 plugins {
+  `java-conventions`
   `java-library`
   `library-publishing-conventions`
 }

sdk-api-gen/build.gradle.kts

@@ -1,5 +1,6 @@
 plugins {
-  java
+  `java-conventions`
+  `test-jar-conventions`
   application
   `library-publishing-conventions`
 }
@@ -27,15 +28,3 @@ dependencies {
   // Import test suites from sdk-core
   testImplementation(project(":sdk-core", "testArchive"))
 }
-
-// Generate test jar
-
-configurations { register("testArchive") }
-
-tasks.register<Jar>("testJar") {
-  archiveClassifier.set("tests")
-
-  from(project.the<SourceSetContainer>()["test"].output)
-}
-
-artifacts { add("testArchive", tasks["testJar"]) }

sdk-api-kotlin-gen/build.gradle.kts

@@ -1,7 +1,6 @@
 plugins {
-  java
-  kotlin("jvm")
-  kotlin("plugin.serialization")
+  `kotlin-conventions`
+  `test-jar-conventions`
   `library-publishing-conventions`
   alias(kotlinLibs.plugins.ksp)
 }
@@ -29,15 +28,3 @@ dependencies {
   // Import test suites from sdk-core
   testImplementation(project(":sdk-core", "testArchive"))
 }
-
-// Generate test jar
-
-configurations { register("testArchive") }
-
-tasks.register<Jar>("testJar") {
-  archiveClassifier.set("tests")
-
-  from(project.the<SourceSetContainer>()["test"].output)
-}
-
-artifacts { add("testArchive", tasks["testJar"]) }

sdk-api-kotlin/build.gradle.kts

@@ -1,7 +1,6 @@
 plugins {
-  java
-  kotlin("jvm")
-  kotlin("plugin.serialization")
+  `kotlin-conventions`
+  `test-jar-conventions`
   `library-publishing-conventions`
 }
 
@@ -27,15 +26,3 @@ dependencies {
 
   testImplementation(project(":sdk-core", "testArchive"))
 }
-
-// Generate test jar
-
-configurations { register("testArchive") }
-
-tasks.register<Jar>("testJar") {
-  archiveClassifier.set("tests")
-
-  from(project.the<SourceSetContainer>()["test"].output)
-}
-
-artifacts { add("testArchive", tasks["testJar"]) }

sdk-api-kotlin/src/main/kotlin/dev/restate/sdk/kotlin/HandlerRunner.kt

@@ -21,7 +21,7 @@ import kotlinx.coroutines.asContextElement
 import kotlinx.coroutines.launch
 import org.apache.logging.log4j.LogManager
 
-/** Adapter class for {@link InvocationHandler} to use the Kotlin API. */
+/** Adapter class for [dev.restate.sdk.common.syscalls.HandlerRunner] to use the Kotlin API. */
 class HandlerRunner<REQ, RES, CTX : Context>
 internal constructor(
     private val runner: suspend (CTX, REQ) -> RES,