From b0afbe15727a826820ec09e564e54e85231775f9 Mon Sep 17 00:00:00 2001 From: Francesco Guardiani Date: Mon, 10 Jun 2024 10:42:35 +0200 Subject: [PATCH] Javadocs (#347) * Reorganize the project in convention scripts * Managed to get the aggregated javadocs * Dokka now works! --- admin-client/build.gradle.kts | 1 + build.gradle.kts | 92 ++++++------------- buildSrc/build.gradle.kts | 9 ++ .../main/kotlin/java-conventions.gradle.kts | 43 +++++++++ .../main/kotlin/kotlin-conventions.gradle.kts | 19 ++++ .../kotlin/test-jar-conventions.gradle.kts | 9 ++ examples/build.gradle.kts | 9 +- .../my/restate/sdk/examples/CounterKt.kt | 10 +- examples/src/main/resources/log4j2.properties | 4 +- sdk-aggregated-javadocs/build.gradle.kts | 17 ++++ sdk-api-gen-common/build.gradle.kts | 1 + sdk-api-gen/build.gradle.kts | 15 +-- sdk-api-kotlin-gen/build.gradle.kts | 17 +--- sdk-api-kotlin/build.gradle.kts | 17 +--- .../dev/restate/sdk/kotlin/HandlerRunner.kt | 2 +- sdk-api/build.gradle.kts | 14 +-- sdk-common/build.gradle.kts | 5 + sdk-core/build.gradle.kts | 28 ++++-- sdk-http-vertx/build.gradle.kts | 3 +- sdk-lambda/build.gradle.kts | 3 +- sdk-request-identity/build.gradle.kts | 2 + sdk-serde-jackson/build.gradle.kts | 2 + sdk-serde-protobuf/build.gradle.kts | 2 + sdk-testing/build.gradle.kts | 2 + settings.gradle.kts | 2 +- 25 files changed, 191 insertions(+), 137 deletions(-) create mode 100644 buildSrc/src/main/kotlin/java-conventions.gradle.kts create mode 100644 buildSrc/src/main/kotlin/kotlin-conventions.gradle.kts create mode 100644 buildSrc/src/main/kotlin/test-jar-conventions.gradle.kts create mode 100644 sdk-aggregated-javadocs/build.gradle.kts diff --git a/admin-client/build.gradle.kts b/admin-client/build.gradle.kts index c2fe24fd..02976348 100644 --- a/admin-client/build.gradle.kts +++ b/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` } diff --git a/build.gradle.kts b/build.gradle.kts index eead1dc6..7382d141 100644 --- a/build.gradle.kts +++ b/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 { - 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().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 { 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 { diff --git a/buildSrc/build.gradle.kts b/buildSrc/build.gradle.kts index 876c922b..21617019 100644 --- a/buildSrc/build.gradle.kts +++ b/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") +} \ No newline at end of file diff --git a/buildSrc/src/main/kotlin/java-conventions.gradle.kts b/buildSrc/src/main/kotlin/java-conventions.gradle.kts new file mode 100644 index 00000000..e34fda5f --- /dev/null +++ b/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().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 { useJUnitPlatform() } + +configure { + java { + targetExclude("build/**/*.java") + + googleJavaFormat() + + licenseHeaderFile("$rootDir/config/license-header") + } +} \ No newline at end of file diff --git a/buildSrc/src/main/kotlin/kotlin-conventions.gradle.kts b/buildSrc/src/main/kotlin/kotlin-conventions.gradle.kts new file mode 100644 index 00000000..22c90348 --- /dev/null +++ b/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 { useJUnitPlatform() } + +configure { + kotlin { + targetExclude("build/generated/**/*.kt") + ktfmt() + licenseHeaderFile("$rootDir/config/license-header") + } +} \ No newline at end of file diff --git a/buildSrc/src/main/kotlin/test-jar-conventions.gradle.kts b/buildSrc/src/main/kotlin/test-jar-conventions.gradle.kts new file mode 100644 index 00000000..7f00d272 --- /dev/null +++ b/buildSrc/src/main/kotlin/test-jar-conventions.gradle.kts @@ -0,0 +1,9 @@ +configurations { register("testArchive") } + +tasks.register("testJar") { + archiveClassifier.set("tests") + + from(project.the()["test"].output) +} + +artifacts { add("testArchive", tasks["testJar"]) } \ No newline at end of file diff --git a/examples/build.gradle.kts b/examples/build.gradle.kts index 1c3b5b6c..3b721b54 100644 --- a/examples/build.gradle.kts +++ b/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 { diff --git a/examples/src/main/kotlin/my/restate/sdk/examples/CounterKt.kt b/examples/src/main/kotlin/my/restate/sdk/examples/CounterKt.kt index 9940e3da..1526d5a6 100644 --- a/examples/src/main/kotlin/my/restate/sdk/examples/CounterKt.kt +++ b/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() } diff --git a/examples/src/main/resources/log4j2.properties b/examples/src/main/resources/log4j2.properties index 536d1d39..109e46d6 100644 --- a/examples/src/main/resources/log4j2.properties +++ b/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 \ No newline at end of file diff --git a/sdk-aggregated-javadocs/build.gradle.kts b/sdk-aggregated-javadocs/build.gradle.kts new file mode 100644 index 00000000..496113a5 --- /dev/null +++ b/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" +} diff --git a/sdk-api-gen-common/build.gradle.kts b/sdk-api-gen-common/build.gradle.kts index 6d69e5b9..81896653 100644 --- a/sdk-api-gen-common/build.gradle.kts +++ b/sdk-api-gen-common/build.gradle.kts @@ -1,4 +1,5 @@ plugins { + `java-conventions` `java-library` `library-publishing-conventions` } diff --git a/sdk-api-gen/build.gradle.kts b/sdk-api-gen/build.gradle.kts index e3446880..66faf963 100644 --- a/sdk-api-gen/build.gradle.kts +++ b/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("testJar") { - archiveClassifier.set("tests") - - from(project.the()["test"].output) -} - -artifacts { add("testArchive", tasks["testJar"]) } diff --git a/sdk-api-kotlin-gen/build.gradle.kts b/sdk-api-kotlin-gen/build.gradle.kts index 1219c574..2befe63c 100644 --- a/sdk-api-kotlin-gen/build.gradle.kts +++ b/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("testJar") { - archiveClassifier.set("tests") - - from(project.the()["test"].output) -} - -artifacts { add("testArchive", tasks["testJar"]) } diff --git a/sdk-api-kotlin/build.gradle.kts b/sdk-api-kotlin/build.gradle.kts index 77265fb9..f04a7682 100644 --- a/sdk-api-kotlin/build.gradle.kts +++ b/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("testJar") { - archiveClassifier.set("tests") - - from(project.the()["test"].output) -} - -artifacts { add("testArchive", tasks["testJar"]) } diff --git a/sdk-api-kotlin/src/main/kotlin/dev/restate/sdk/kotlin/HandlerRunner.kt b/sdk-api-kotlin/src/main/kotlin/dev/restate/sdk/kotlin/HandlerRunner.kt index 2099354b..fde1405b 100644 --- a/sdk-api-kotlin/src/main/kotlin/dev/restate/sdk/kotlin/HandlerRunner.kt +++ b/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 internal constructor( private val runner: suspend (CTX, REQ) -> RES, diff --git a/sdk-api/build.gradle.kts b/sdk-api/build.gradle.kts index 8d3c378e..a4b25a12 100644 --- a/sdk-api/build.gradle.kts +++ b/sdk-api/build.gradle.kts @@ -1,5 +1,7 @@ plugins { + `java-conventions` `java-library` + `test-jar-conventions` `library-publishing-conventions` } @@ -25,15 +27,3 @@ dependencies { // Import test suites from sdk-core testImplementation(project(":sdk-core", "testArchive")) } - -// Generate test jar - -configurations { register("testArchive") } - -tasks.register("testJar") { - archiveClassifier.set("tests") - - from(project.the()["test"].output) -} - -artifacts { add("testArchive", tasks["testJar"]) } diff --git a/sdk-common/build.gradle.kts b/sdk-common/build.gradle.kts index e1d8e5a7..372865fa 100644 --- a/sdk-common/build.gradle.kts +++ b/sdk-common/build.gradle.kts @@ -1,5 +1,9 @@ +import org.jetbrains.dokka.gradle.AbstractDokkaTask + plugins { `java-library` + `java-conventions` + `kotlin-conventions` `library-publishing-conventions` } @@ -80,4 +84,5 @@ val generateVersionClass = tasks { withType().configureEach { dependsOn(generateVersionClass) } withType().configureEach { dependsOn(generateVersionClass) } + withType().configureEach { dependsOn(generateVersionClass) } } diff --git a/sdk-core/build.gradle.kts b/sdk-core/build.gradle.kts index ab85a10f..0a6da633 100644 --- a/sdk-core/build.gradle.kts +++ b/sdk-core/build.gradle.kts @@ -1,8 +1,16 @@ +import org.jetbrains.dokka.gradle.AbstractDokkaTask + plugins { `java-library` + `java-conventions` + `kotlin-conventions` + `test-jar-conventions` `library-publishing-conventions` id("org.jsonschema2pojo") version "1.2.1" alias(pluginLibs.plugins.protobuf) + + // https://github.com/gradle/gradle/issues/20084#issuecomment-1060822638 + id(pluginLibs.plugins.spotless.get().pluginId) apply false } description = "Restate SDK Core" @@ -66,17 +74,21 @@ protobuf { protoc { artifact = "com.google.protobuf:protoc:$protobufVersion" } } tasks { withType { dependsOn(generateJsonSchema2Pojo, generateProto) } withType { dependsOn(generateJsonSchema2Pojo, generateProto) } + withType().configureEach { dependsOn(generateJsonSchema2Pojo, generateProto) } } -// Generate test jar +// spotless configuration for protobuf -configurations { register("testArchive") } +configure { + format("proto") { + target("**/*.proto") -tasks.register("testJar") { - archiveClassifier.set("tests") + // 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("**/*.*") }) - from(project.the()["test"].output) - exclude("junit-platform.properties") + licenseHeaderFile("$rootDir/config/license-header", "syntax") + } } - -artifacts { add("testArchive", tasks["testJar"]) } diff --git a/sdk-http-vertx/build.gradle.kts b/sdk-http-vertx/build.gradle.kts index c790a058..3db6f347 100644 --- a/sdk-http-vertx/build.gradle.kts +++ b/sdk-http-vertx/build.gradle.kts @@ -1,6 +1,7 @@ plugins { + `java-conventions` + `kotlin-conventions` `java-library` - kotlin("jvm") `library-publishing-conventions` } diff --git a/sdk-lambda/build.gradle.kts b/sdk-lambda/build.gradle.kts index e9a1c3da..c9801e3e 100644 --- a/sdk-lambda/build.gradle.kts +++ b/sdk-lambda/build.gradle.kts @@ -1,6 +1,7 @@ plugins { + `java-conventions` + `kotlin-conventions` `java-library` - kotlin("jvm") `library-publishing-conventions` } diff --git a/sdk-request-identity/build.gradle.kts b/sdk-request-identity/build.gradle.kts index 10c0c454..3357743f 100644 --- a/sdk-request-identity/build.gradle.kts +++ b/sdk-request-identity/build.gradle.kts @@ -1,4 +1,6 @@ plugins { + `java-conventions` + `kotlin-conventions` `java-library` `library-publishing-conventions` } diff --git a/sdk-serde-jackson/build.gradle.kts b/sdk-serde-jackson/build.gradle.kts index 2f3c38a7..c37c9856 100644 --- a/sdk-serde-jackson/build.gradle.kts +++ b/sdk-serde-jackson/build.gradle.kts @@ -1,4 +1,6 @@ plugins { + `java-conventions` + `kotlin-conventions` `java-library` `library-publishing-conventions` } diff --git a/sdk-serde-protobuf/build.gradle.kts b/sdk-serde-protobuf/build.gradle.kts index 99244365..64d5d1ed 100644 --- a/sdk-serde-protobuf/build.gradle.kts +++ b/sdk-serde-protobuf/build.gradle.kts @@ -1,4 +1,6 @@ plugins { + `java-conventions` + `kotlin-conventions` `java-library` `library-publishing-conventions` } diff --git a/sdk-testing/build.gradle.kts b/sdk-testing/build.gradle.kts index 8692bfd4..818067ce 100644 --- a/sdk-testing/build.gradle.kts +++ b/sdk-testing/build.gradle.kts @@ -1,4 +1,6 @@ plugins { + `java-conventions` + `kotlin-conventions` `java-library` `library-publishing-conventions` } diff --git a/settings.gradle.kts b/settings.gradle.kts index 0e2aec24..2398d547 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -27,7 +27,7 @@ include( "sdk-api-gen", "sdk-api-kotlin-gen", "examples", -) + "sdk-aggregated-javadocs") dependencyResolutionManagement { repositories { mavenCentral() }