Mark utilities.* API as Dokka-internal

* Deprecate unused declaration, remove inline declaration (as it's binary compatible), opt-in into internal API at project level * Opt-in into DokkaInternalApi where applicable * Get rid of intermediate test-utils module
Kotlin · Mar 23, 2023 · 0139016 · 0139016
1 parent ff5aa67
commit 0139016
Show file tree

Hide file tree

Showing 38 changed files with 54 additions and 66 deletions.
diff --git a/build-logic/src/main/kotlin/org/jetbrains/conventions/base-java.gradle.kts b/build-logic/src/main/kotlin/org/jetbrains/conventions/base-java.gradle.kts
@@ -43,4 +43,6 @@ dependencies {
     // repetitive, but more declarative and clear), or some other solution.
     testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine")
     testRuntimeOnly("org.junit.vintage:junit-vintage-engine")
+    // kotlin-test asserts for all projects
+    testImplementation(kotlin("test-junit"))
 }
diff --git a/build-logic/src/main/kotlin/org/jetbrains/conventions/kotlin-jvm.gradle.kts b/build-logic/src/main/kotlin/org/jetbrains/conventions/kotlin-jvm.gradle.kts
@@ -11,15 +11,21 @@ plugins {
 
 configureDokkaVersion()
 
+val projectsWithoutOptInDependency = setOf(
+    ":integration-tests", ":integration-tests:gradle", ":integration-tests:maven", ":integration-tests:cli")
+
 tasks.withType<KotlinCompile>().configureEach {
+    // By path because Dokka has multiple projects with the same name (i.e. 'cli')
+    if (project.path in projectsWithoutOptInDependency) return@configureEach
     compilerOptions {
         freeCompilerArgs.addAll(
             listOf(
                 "-opt-in=kotlin.RequiresOptIn",
+                "-opt-in=org.jetbrains.dokka.InternalDokkaApi",
                 "-Xjsr305=strict",
                 "-Xskip-metadata-version-check",
                 // need 1.4 support, otherwise there might be problems with Gradle 6.x (it's bundling Kotlin 1.4)
-                "-Xsuppress-version-warnings"
+                "-Xsuppress-version-warnings",
             )
         )
         allWarningsAsErrors.set(true)

diff --git a/build.gradle.kts b/build.gradle.kts
@@ -1,4 +1,5 @@
 import org.jetbrains.ValidatePublications
+import org.jetbrains.kotlin.gradle.tasks.*
 import org.jetbrains.publicationChannels
 
 @Suppress("DSL_SCOPE_VIOLATION") // fixed in Gradle 8.1 https://github.com/gradle/gradle/pull/23639
@@ -50,7 +51,5 @@ apiValidation {
         "gradle",              // :integration-tests:gradle
         "cli",                 // :integration-tests:cli
         "maven",               // integration-tests:maven
-
-        "test-utils",          // :test-utils
     )
 }
diff --git a/core/api/core.api b/core/api/core.api
@@ -4580,7 +4580,6 @@ public final class org/jetbrains/dokka/utilities/DokkaConsoleLogger : org/jetbra
 	public fun debug (Ljava/lang/String;)V
 	public fun error (Ljava/lang/String;)V
 	public fun getErrorsCount ()I
-	public final fun getMinLevel ()Lorg/jetbrains/dokka/utilities/LoggingLevel;
 	public fun getWarningsCount ()I
 	public fun info (Ljava/lang/String;)V
 	public fun progress (Ljava/lang/String;)V

diff --git a/core/build.gradle.kts b/core/build.gradle.kts
@@ -40,12 +40,6 @@ tasks {
     }
 }
 
-tasks.withType(KotlinCompile::class).all {
-    kotlinOptions {
-        freeCompilerArgs = freeCompilerArgs + listOf("-opt-in=org.jetbrains.dokka.InternalDokkaApi",)
-    }
-}
-
 registerDokkaArtifactPublication("dokkaCore") {
     artifactId = "dokka-core"
 }
diff --git a/core/src/main/kotlin/utilities/DokkaLogging.kt b/core/src/main/kotlin/utilities/DokkaLogging.kt
@@ -39,7 +39,7 @@ fun interface MessageEmitter : (String) -> Unit {
 }
 
 class DokkaConsoleLogger(
-    val minLevel: LoggingLevel = LoggingLevel.PROGRESS,
+    private val minLevel: LoggingLevel = LoggingLevel.PROGRESS,
     private val emitter: MessageEmitter = MessageEmitter.consoleEmitter
 ) : DokkaLogger {
     private val warningsCounter = AtomicInteger()

diff --git a/core/src/main/kotlin/utilities/Html.kt b/core/src/main/kotlin/utilities/Html.kt
@@ -1,15 +1,19 @@
 package org.jetbrains.dokka.utilities
 
+import org.jetbrains.dokka.*
 import java.net.URLEncoder
 
 
 /**
  * Replaces symbols reserved in HTML with their respective entities.
  * Replaces & with &amp;, < with &lt; and > with &gt;
  */
+@InternalDokkaApi
 fun String.htmlEscape(): String = replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").replace("\"", "&quot;")
 
+@InternalDokkaApi
 fun String.urlEncoded(): String = URLEncoder.encode(this, "UTF-8")
 
+@InternalDokkaApi
 fun String.formatToEndWithHtml() =
     if (endsWith(".html") || contains(Regex("\\.html#"))) this else "$this.html"
diff --git a/core/src/main/kotlin/utilities/ServiceLocator.kt b/core/src/main/kotlin/utilities/ServiceLocator.kt
@@ -1,16 +1,20 @@
 package org.jetbrains.dokka.utilities
 
+import org.jetbrains.dokka.*
 import java.io.File
 import java.net.URISyntaxException
 import java.net.URL
 import java.util.*
 import java.util.jar.JarFile
 import java.util.zip.ZipEntry
 
+@InternalDokkaApi
 data class ServiceDescriptor(val name: String, val category: String, val description: String?, val className: String)
 
+@InternalDokkaApi
 class ServiceLookupException(message: String) : Exception(message)
 
+@InternalDokkaApi
 object ServiceLocator {
     fun <T : Any> lookup(clazz: Class<T>, category: String, implementationName: String): T {
         val descriptor = lookupDescriptor(category, implementationName)
@@ -81,9 +85,6 @@ object ServiceLocator {
     }
 }
 
-inline fun <reified T : Any> ServiceLocator.lookup(category: String, implementationName: String): T = lookup(T::class.java, category, implementationName)
-inline fun <reified T : Any> ServiceLocator.lookup(desc: ServiceDescriptor): T = lookup(T::class.java, desc)
-
 private val ZipEntry.fileName: String
     get() = name.substringAfterLast("/", name)
 

diff --git a/core/src/main/kotlin/utilities/Uri.kt b/core/src/main/kotlin/utilities/Uri.kt
@@ -1,8 +1,10 @@
 package org.jetbrains.dokka.utilities
 
+import org.jetbrains.dokka.*
 import java.net.URI
 
-
+@InternalDokkaApi
+@Deprecated("Deprecated for removal") // Unused in Dokka
 fun URI.relativeTo(uri: URI): URI {
     // Normalize paths to remove . and .. segments
     val base = uri.normalize()
@@ -37,4 +39,4 @@ fun URI.relativeTo(uri: URI): URI {
             append(it)
         }
     })
-}
+}
diff --git a/core/src/main/kotlin/utilities/associateWithNotNull.kt b/core/src/main/kotlin/utilities/associateWithNotNull.kt
@@ -1,5 +1,8 @@
 package org.jetbrains.dokka.utilities
 
+import org.jetbrains.dokka.*
+
+@InternalDokkaApi
 inline fun <K, V : Any> Iterable<K>.associateWithNotNull(valueSelector: (K) -> V?): Map<K, V> {
     @Suppress("UNCHECKED_CAST")
     return associateWith { valueSelector(it) }.filterValues { it != null } as Map<K, V>

diff --git a/core/src/main/kotlin/utilities/cast.kt b/core/src/main/kotlin/utilities/cast.kt
@@ -1,5 +1,8 @@
 package org.jetbrains.dokka.utilities
 
+import org.jetbrains.dokka.*
+
+@InternalDokkaApi
 inline fun <reified T> Any.cast(): T {
     return this as T
 }
diff --git a/core/src/main/kotlin/utilities/parallelCollectionOperations.kt b/core/src/main/kotlin/utilities/parallelCollectionOperations.kt
@@ -1,15 +1,19 @@
 package org.jetbrains.dokka.utilities
 
 import kotlinx.coroutines.*
+import org.jetbrains.dokka.*
 
+@InternalDokkaApi
 suspend inline fun <A, B> Iterable<A>.parallelMap(crossinline f: suspend (A) -> B): List<B> = coroutineScope {
     map { async { f(it) } }.awaitAll()
 }
 
+@InternalDokkaApi
 suspend inline fun <A, B> Iterable<A>.parallelMapNotNull(crossinline f: suspend (A) -> B?): List<B> = coroutineScope {
     map { async { f(it) } }.awaitAll().filterNotNull()
 }
 
+@InternalDokkaApi
 suspend inline fun <A> Iterable<A>.parallelForEach(crossinline f: suspend (A) -> Unit): Unit = coroutineScope {
     forEach { launch { f(it) } }
 }
diff --git a/integration-tests/build.gradle.kts b/integration-tests/build.gradle.kts
@@ -3,7 +3,7 @@ plugins {
 }
 
 dependencies {
-    api(projects.testUtils)
+    implementation(kotlin("test-junit"))
     implementation(libs.kotlinx.coroutines.core)
     implementation(libs.jsoup)
     implementation(libs.eclipse.jgit)

diff --git a/...src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/Android0GradleIntegrationTest.kt b/...src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/Android0GradleIntegrationTest.kt
@@ -1,17 +1,32 @@
 package org.jetbrains.dokka.it.gradle
 
 import org.gradle.testkit.runner.TaskOutcome
-import org.jetbrains.dokka.test.assumeAndroidSdkInstalled
+import org.junit.*
 import org.junit.runners.Parameterized.Parameters
 import java.io.File
 import kotlin.test.*
+import kotlin.test.Test
 
 class Android0GradleIntegrationTest(override val versions: BuildVersions) : AbstractGradleIntegrationTest() {
 
     companion object {
         @get:JvmStatic
         @get:Parameters(name = "{0}")
         val versions = TestedVersions.ANDROID
+
+        /**
+         * Indicating whether or not the current machine executing the test is a CI
+         */
+        private val isCI: Boolean get() = System.getenv("CI") == "true"
+
+        private val isAndroidSdkInstalled: Boolean = System.getenv("ANDROID_SDK_ROOT") != null ||
+                System.getenv("ANDROID_HOME") != null
+
+        fun assumeAndroidSdkInstalled() {
+            if (isCI) return
+            Assume.assumeTrue(isAndroidSdkInstalled)
+        }
+
     }
 
     @BeforeTest

diff --git a/integration-tests/src/main/kotlin/org/jetbrains/dokka/it/gitSubmoduleUtils.kt b/integration-tests/src/main/kotlin/org/jetbrains/dokka/it/gitSubmoduleUtils.kt
@@ -34,7 +34,7 @@ fun AbstractIntegrationTest.applyGitDiffFromFile(diffFile: File) {
 private fun removeGitFile(repository: Path) =
     repository.toFile()
         .listFiles().orEmpty()
-        .filter { it.name.toLowerCase() == ".git" }
+        .filter { it.name.lowercase() == ".git" }
         .forEach { it.delete() }
 
 
diff --git a/plugins/all-modules-page/build.gradle.kts b/plugins/all-modules-page/build.gradle.kts
@@ -32,7 +32,6 @@ dependencies {
     implementation(libs.kotlinx.html)
     implementation(libs.jsoup)
 
-    testImplementation(projects.testUtils)
     testImplementation(projects.core.testApi)
     testImplementation(platform(libs.junit.bom))
     testImplementation(libs.junit.jupiter)

diff --git a/plugins/android-documentation/build.gradle.kts b/plugins/android-documentation/build.gradle.kts
@@ -13,7 +13,6 @@ dependencies {
 
     testImplementation(projects.plugins.base)
     testImplementation(projects.plugins.base.baseTestUtils)
-    testImplementation(projects.testUtils)
     testImplementation(projects.core.testApi)
     testImplementation(platform(libs.junit.bom))
     testImplementation(libs.junit.jupiter)

diff --git a/plugins/base/base-test-utils/build.gradle.kts b/plugins/base/base-test-utils/build.gradle.kts
@@ -17,7 +17,6 @@ dependencies {
     implementation(libs.jsoup)
     implementation(kotlin("test-junit"))
 
-    testImplementation(projects.testUtils)
     testImplementation(projects.core.testApi)
     testImplementation(platform(libs.junit.bom))
     testImplementation(libs.junit.jupiter)

diff --git a/plugins/base/build.gradle.kts b/plugins/base/build.gradle.kts
@@ -30,7 +30,6 @@ dependencies {
     implementation(libs.kotlinx.html)
 
     testImplementation(projects.kotlinAnalysis)
-    testImplementation(projects.testUtils)
     testImplementation(projects.core.testApi)
     testImplementation(platform(libs.junit.bom))
     testImplementation(libs.junit.jupiter)

diff --git a/plugins/gfm/build.gradle.kts b/plugins/gfm/build.gradle.kts
@@ -12,7 +12,6 @@ dependencies {
     testImplementation(projects.plugins.base)
     testImplementation(projects.plugins.base.baseTestUtils)
     implementation(libs.jackson.kotlin)
-    testImplementation(projects.testUtils)
     testImplementation(projects.core.testApi)
     testImplementation(platform(libs.junit.bom))
     testImplementation(libs.junit.jupiter)

diff --git a/plugins/gfm/gfm-template-processing/build.gradle.kts b/plugins/gfm/gfm-template-processing/build.gradle.kts
@@ -16,7 +16,6 @@ dependencies {
 
     implementation(libs.kotlinx.coroutines.core)
 
-    testImplementation(projects.testUtils)
     testImplementation(projects.core.testApi)
     testImplementation(platform(libs.junit.bom))
     testImplementation(libs.junit.jupiter)

diff --git a/plugins/javadoc/build.gradle.kts b/plugins/javadoc/build.gradle.kts
@@ -18,7 +18,6 @@ dependencies {
     implementation(libs.kotlinx.coroutines.core)
 
     testImplementation(projects.plugins.base.baseTestUtils)
-    testImplementation(projects.testUtils)
     testImplementation(projects.core.testApi)
 
     testImplementation(libs.jsoup)

diff --git a/.../jetbrains/dokka/test/assertIsInstance.kt → ...in/org/jetbrains/dokka/javadoc/Asserts.kt b/.../jetbrains/dokka/test/assertIsInstance.kt → ...in/org/jetbrains/dokka/javadoc/Asserts.kt
@@ -1,8 +1,8 @@
-package org.jetbrains.dokka.test
+package org.jetbrains.dokka.javadoc
 
-import kotlin.contracts.ExperimentalContracts
-import kotlin.contracts.contract
+import kotlin.contracts.*
 
+// TODO replace with assertIs<T> from kotlin-test as part of #2924
 @OptIn(ExperimentalContracts::class)
 inline fun <reified T> assertIsInstance(obj: Any?): T {
     contract {

diff --git a/...s/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocAllClassesTemplateMapTest.kt b/...s/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocAllClassesTemplateMapTest.kt
@@ -4,7 +4,6 @@ import org.jetbrains.dokka.javadoc.pages.AllClassesPage
 import org.jetbrains.dokka.javadoc.pages.LinkJavadocListEntry
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.pages.ContentKind
-import org.jetbrains.dokka.test.assertIsInstance
 import org.junit.jupiter.api.Assertions.assertEquals
 import org.junit.jupiter.api.Test
 

diff --git a/...ns/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocClasslikeTemplateMapTest.kt b/...ns/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocClasslikeTemplateMapTest.kt
@@ -3,7 +3,6 @@ package org.jetbrains.dokka.javadoc
 import org.jetbrains.dokka.javadoc.pages.JavadocClasslikePageNode
 import org.junit.jupiter.api.Assertions.assertEquals
 import org.junit.jupiter.api.Test
-import org.jetbrains.dokka.test.assertIsInstance
 
 internal class JavadocClasslikeTemplateMapTest : AbstractJavadocTemplateMapTest() {
 

diff --git a/plugins/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocModuleTemplateMapTest.kt b/plugins/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocModuleTemplateMapTest.kt
@@ -3,7 +3,6 @@ package org.jetbrains.dokka.javadoc
 import org.jetbrains.dokka.javadoc.pages.JavadocModulePageNode
 import org.jetbrains.dokka.javadoc.pages.RowJavadocListEntry
 import org.jetbrains.dokka.links.DRI
-import org.jetbrains.dokka.test.assertIsInstance
 import org.junit.jupiter.api.Assertions.assertEquals
 import org.junit.jupiter.api.Test
 import java.io.File

diff --git a/plugins/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocPackageTemplateMapTest.kt b/plugins/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocPackageTemplateMapTest.kt
@@ -4,7 +4,6 @@ import org.jetbrains.dokka.javadoc.pages.JavadocContentKind
 import org.jetbrains.dokka.javadoc.pages.JavadocPackagePageNode
 import org.jetbrains.dokka.javadoc.pages.RowJavadocListEntry
 import org.jetbrains.dokka.links.DRI
-import org.jetbrains.dokka.test.assertIsInstance
 import org.junit.jupiter.api.Assertions.assertEquals
 import org.junit.jupiter.api.Test
 import java.io.File

diff --git a/plugins/jekyll/build.gradle.kts b/plugins/jekyll/build.gradle.kts
@@ -11,7 +11,6 @@ dependencies {
     implementation(projects.plugins.base)
     implementation(projects.plugins.gfm)
 
-    testImplementation(projects.testUtils)
     testImplementation(projects.core.testApi)
     testImplementation(platform(libs.junit.bom))
     testImplementation(libs.junit.jupiter)

diff --git a/plugins/jekyll/jekyll-template-processing/build.gradle.kts b/plugins/jekyll/jekyll-template-processing/build.gradle.kts
@@ -18,7 +18,6 @@ dependencies {
 
     implementation(libs.kotlinx.coroutines.core)
 
-    testImplementation(projects.testUtils)
     testImplementation(projects.core.testApi)
     testImplementation(platform(libs.junit.bom))
     testImplementation(libs.junit.jupiter)

diff --git a/plugins/kotlin-as-java/build.gradle.kts b/plugins/kotlin-as-java/build.gradle.kts
@@ -16,7 +16,6 @@ dependencies {
     testImplementation(libs.jsoup)
     testImplementation(projects.kotlinAnalysis)
 
-    testImplementation(projects.testUtils)
     testImplementation(projects.core.testApi)
     testImplementation(platform(libs.junit.bom))
     testImplementation(libs.junit.jupiter)

diff --git a/plugins/mathjax/build.gradle.kts b/plugins/mathjax/build.gradle.kts
@@ -16,7 +16,6 @@ dependencies {
     testImplementation(kotlin("test-junit"))
     testImplementation(projects.kotlinAnalysis)
 
-    testImplementation(projects.testUtils)
     testImplementation(projects.core.testApi)
     testImplementation(platform(libs.junit.bom))
     testImplementation(libs.junit.jupiter)

diff --git a/plugins/templating/build.gradle.kts b/plugins/templating/build.gradle.kts
@@ -28,7 +28,6 @@ dependencies {
     implementation(libs.jsoup)
     testImplementation(projects.plugins.base.baseTestUtils)
 
-    testImplementation(projects.testUtils)
     testImplementation(projects.core.testApi)
     testImplementation(platform(libs.junit.bom))
     testImplementation(libs.junit.jupiter)

diff --git a/plugins/versioning/build.gradle.kts b/plugins/versioning/build.gradle.kts
@@ -28,7 +28,6 @@ dependencies {
     implementation(libs.jsoup)
     implementation(libs.apache.mavenArtifact)
 
-    testImplementation(projects.testUtils)
     testImplementation(projects.core.testApi)
     testImplementation(platform(libs.junit.bom))
     testImplementation(libs.junit.jupiter)

diff --git a/runners/gradle-plugin/build.gradle.kts b/runners/gradle-plugin/build.gradle.kts
@@ -13,7 +13,6 @@ dependencies {
     compileOnly(libs.gradlePlugin.kotlin)
     compileOnly(libs.gradlePlugin.android)
 
-    testImplementation(projects.testUtils)
     testImplementation(libs.gradlePlugin.kotlin)
     testImplementation(libs.gradlePlugin.android)
 }

diff --git a/settings.gradle.kts b/settings.gradle.kts
@@ -88,8 +88,6 @@ include(
     ":integration-tests:cli",
     ":integration-tests:maven",
 
-    ":test-utils",
-
     ":mkdocs",
 )