Fix javadoc missing generated API (#200)

Move Dokka configuration to the `jvm-library` plugin, which is applied
before `test-suites`, and stop passing a fixed source root for Dokka so
that generated API source set is included. Also fix some configuration
avoidance smells.

When refactoring build logic into plugins, Dokka stopped recognizing the
correct source set. #199 fixed this by passing a specific source root to
Dokka, but this caused the resulting javadoc to not include the
generated API. Bisecting shows that moving the test suite setup
(456f769), making test suites be set up
before Dokka, was when the issue started.

Author: gabrielfeo

build-logic/build.gradle.kts

@@ -18,6 +18,7 @@ gradlePlugin {
 
 dependencies {
     implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.23")
+    implementation("org.jetbrains.dokka:dokka-gradle-plugin:1.9.20")
     implementation("org.openapitools:openapi-generator-gradle-plugin:7.4.0")
     "functionalTestImplementation"(project)
 }

build-logic/src/main/kotlin/com/gabrielfeo/kotlin-jvm-library.gradle.kts

@@ -1,6 +1,49 @@
 package com.gabrielfeo
 
+import org.jetbrains.dokka.DokkaConfiguration.Visibility.PUBLIC
+import org.jetbrains.dokka.gradle.DokkaTask
+import java.net.URL
+
 plugins {
     id("org.jetbrains.kotlin.jvm")
+    id("org.jetbrains.dokka")
     `java-library`
 }
+
+val repoUrl: Provider<String> = providers.gradleProperty("repo.url")
+
+java {
+    withSourcesJar()
+    withJavadocJar()
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(11))
+        vendor.set(JvmVendorSpec.AZUL)
+    }
+}
+
+tasks.withType<DokkaTask>().configureEach {
+    dokkaSourceSets.all {
+        sourceRoot("src/main/kotlin")
+        sourceLink {
+            localDirectory.set(file("src/main/kotlin"))
+            remoteUrl.set(repoUrl.map { URL("$it/blob/$version/src/main/kotlin") })
+            remoteLineSuffix.set("#L")
+        }
+        jdkVersion.set(11)
+        suppressGeneratedFiles.set(false)
+        documentedVisibilities.set(setOf(PUBLIC))
+        perPackageOption {
+            matchingRegex.set(""".*\.internal.*""")
+            suppress.set(true)
+        }
+        externalDocumentationLink("https://kotlinlang.org/api/kotlinx.coroutines/")
+        externalDocumentationLink("https://square.github.io/okhttp/4.x/okhttp/")
+        externalDocumentationLink("https://square.github.io/retrofit/2.x/retrofit/")
+        externalDocumentationLink("https://square.github.io/moshi/1.x/moshi/")
+        externalDocumentationLink("https://square.github.io/moshi/1.x/moshi-kotlin/")
+    }
+}
+
+tasks.named<Jar>("javadocJar") {
+    from(tasks.dokkaHtml)
+}

build-logic/src/main/kotlin/com/gabrielfeo/test-suites.gradle.kts

@@ -34,7 +34,7 @@ kotlin {
 }
 
 // TODO Unapply test-fixtures and delete the source set, since we're not publishing it?
-components.getByName<AdhocComponentWithVariants>("java").apply {
+components.named<AdhocComponentWithVariants>("java") {
     withVariantsFromConfiguration(configurations["testFixturesApiElements"]) { skip() }
     withVariantsFromConfiguration(configurations["testFixturesRuntimeElements"]) { skip() }
 }

build.gradle.kts

@@ -1,3 +0,0 @@
-plugins {
-    id("org.jetbrains.dokka") version "1.9.20" apply false
-}

gradle.properties

@@ -2,6 +2,7 @@ group=com.gabrielfeo
 artifact=develocity-api-kotlin
 version=2024.1.0
 develocity.version=2024.1
+repo.url=https://github.com/gabrielfeo/develocity-api-kotlin
 org.gradle.jvmargs=-Xmx5g
 org.gradle.caching=true
 # Becomes default in Gradle 9.0

library/build.gradle.kts

@@ -8,57 +8,18 @@ plugins {
     id("com.gabrielfeo.kotlin-jvm-library")
     id("com.gabrielfeo.develocity-api-code-generation")
     id("com.gabrielfeo.test-suites")
-    id("org.jetbrains.dokka")
     `java-library`
     `maven-publish`
     signing
     kotlin("jupyter.api") version "0.12.0-181"
 }
 
-val repoUrl = "https://github.com/gabrielfeo/develocity-api-kotlin"
-
-java {
-    withSourcesJar()
-    withJavadocJar()
-    toolchain {
-        languageVersion.set(JavaLanguageVersion.of(11))
-        vendor.set(JvmVendorSpec.AZUL)
-    }
-}
-
-tasks.withType<DokkaTask>().configureEach {
-    dokkaSourceSets.register("main") {
-        sourceRoot("src/main/kotlin")
-        sourceLink {
-            localDirectory.set(file("src/main/kotlin"))
-            remoteUrl.set(URL("$repoUrl/blob/$version/src/main/kotlin"))
-            remoteLineSuffix.set("#L")
-        }
-        jdkVersion.set(11)
-        suppressGeneratedFiles.set(false)
-        documentedVisibilities.set(setOf(PUBLIC))
-        perPackageOption {
-            matchingRegex.set(""".*\.internal.*""")
-            suppress.set(true)
-        }
-        externalDocumentationLink("https://kotlinlang.org/api/kotlinx.coroutines/")
-        externalDocumentationLink("https://square.github.io/okhttp/4.x/okhttp/")
-        externalDocumentationLink("https://square.github.io/retrofit/2.x/retrofit/")
-        externalDocumentationLink("https://square.github.io/moshi/1.x/moshi/")
-        externalDocumentationLink("https://square.github.io/moshi/1.x/moshi-kotlin/")
-    }
-}
-
 tasks.processJupyterApiResources {
     libraryProducers = listOf(
         "com.gabrielfeo.develocity.api.internal.jupyter.DevelocityApiJupyterIntegration",
     )
 }
 
-tasks.named<Jar>("javadocJar") {
-    from(tasks.dokkaHtml)
-}
-
 tasks.named<Test>("integrationTest") {
     environment("DEVELOCITY_API_LOG_LEVEL", "DEBUG")
 }
@@ -94,6 +55,7 @@ dependencies {
 val libraryPom = Action<MavenPom> {
     name.set("Develocity API Kotlin")
     description.set("A library to use the Develocity API in Kotlin")
+    val repoUrl = providers.gradleProperty("repo.url")
     url.set(repoUrl)
     licenses {
         license {
@@ -110,27 +72,27 @@ val libraryPom = Action<MavenPom> {
         }
     }
     scm {
-        val basicUrl = repoUrl.substringAfter("://")
-        connection.set("scm:git:git://$basicUrl.git")
-        developerConnection.set("scm:git:ssh://$basicUrl.git")
-        url.set("https://$basicUrl/")
+        val basicUrl = repoUrl.map { it.substringAfter("://") }
+        connection.set(basicUrl.map { "scm:git:git://$it.git" })
+        developerConnection.set(basicUrl.map { "scm:git:ssh://$it.git" })
+        url.set(basicUrl.map { "https://$it/" })
     }
 }
 
 publishing {
     publications {
-        create<MavenPublication>("develocityApiKotlin") {
+        register<MavenPublication>("develocityApiKotlin") {
             artifactId = "develocity-api-kotlin"
             from(components["java"])
             pom(libraryPom)
         }
         // For occasional maven local publishing
-        create<MavenPublication>("unsignedDevelocityApiKotlin") {
+        register<MavenPublication>("unsignedDevelocityApiKotlin") {
             artifactId = "develocity-api-kotlin"
             from(components["java"])
             pom(libraryPom)
         }
-        create<MavenPublication>("relocation") {
+        register<MavenPublication>("relocation") {
             artifactId = "gradle-enterprise-api-kotlin"
             pom {
                 libraryPom(this)
@@ -165,10 +127,10 @@ publishing {
 fun isCI() = System.getenv("CI").toBoolean()
 
 signing {
-    sign(
-        publishing.publications["develocityApiKotlin"],
-        publishing.publications["relocation"],
-    )
+    val signedPublications = publishing.publications.matching {
+        !it.name.contains("unsigned", ignoreCase = true)
+    }
+    sign(signedPublications)
     if (isCI()) {
         useInMemoryPgpKeys(
             project.properties["signing.secretKey"] as String?,