Contribute Dokkatoo (#3188)

8 files changed, 502 insertions, 0 deletions

diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/DokkatooPluginTest.kt b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/DokkatooPluginTest.kt
new file mode 100644
index 00000000..843708a3
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/DokkatooPluginTest.kt
@@ -0,0 +1,76 @@
+package org.jetbrains.dokka.dokkatoo
+
+import org.jetbrains.dokka.dokkatoo.utils.create_
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.string.shouldEndWith
+import org.gradle.kotlin.dsl.*
+import org.gradle.testfixtures.ProjectBuilder
+
+class DokkatooPluginTest : FunSpec({
+
+  test("expect plugin id can be applied to project successfully") {
+    val project = ProjectBuilder.builder().build()
+    project.plugins.apply("org.jetbrains.dokka.dokkatoo")
+    project.plugins.hasPlugin("org.jetbrains.dokka.dokkatoo") shouldBe true
+    project.plugins.hasPlugin(DokkatooPlugin::class) shouldBe true
+  }
+
+  test("expect plugin class can be applied to project successfully") {
+    val project = ProjectBuilder.builder().build()
+    project.plugins.apply(type = DokkatooPlugin::class)
+    project.plugins.hasPlugin("org.jetbrains.dokka.dokkatoo") shouldBe true
+    project.plugins.hasPlugin(DokkatooPlugin::class) shouldBe true
+  }
+
+  context("Dokkatoo property conventions") {
+    val project = ProjectBuilder.builder().build()
+    project.plugins.apply("org.jetbrains.dokka.dokkatoo")
+
+    val extension = project.extensions.getByType<DokkatooExtension>()
+
+    context("DokkatooSourceSets") {
+      val testSourceSet = extension.dokkatooSourceSets.create_("Test") {
+        externalDocumentationLinks.create_("gradle") {
+          url("https://docs.gradle.org/7.6.1/javadoc")
+        }
+      }
+
+      context("JDK external documentation link") {
+        val jdkLink = testSourceSet.externalDocumentationLinks.getByName("jdk")
+
+        test("when enableJdkDocumentationLink is false, expect jdk link is disabled") {
+          testSourceSet.enableJdkDocumentationLink.set(false)
+          jdkLink.enabled.get() shouldBe false
+        }
+
+        test("when enableJdkDocumentationLink is true, expect jdk link is enabled") {
+          testSourceSet.enableJdkDocumentationLink.set(true)
+          jdkLink.enabled.get() shouldBe true
+        }
+
+        (5..10).forEach { jdkVersion ->
+          test("when jdkVersion is $jdkVersion, expect packageListUrl uses package-list file") {
+            testSourceSet.jdkVersion.set(jdkVersion)
+            jdkLink.packageListUrl.get().toString() shouldEndWith "package-list"
+          }
+        }
+
+        (11..22).forEach { jdkVersion ->
+          test("when jdkVersion is $jdkVersion, expect packageListUrl uses element-list file") {
+            testSourceSet.jdkVersion.set(jdkVersion)
+            jdkLink.packageListUrl.get().toString() shouldEndWith "element-list"
+          }
+        }
+      }
+
+      context("external doc links") {
+        test("package-list url should be appended to Javadoc URL") {
+          val gradleDocLink = testSourceSet.externalDocumentationLinks.getByName("gradle")
+          gradleDocLink.packageListUrl.get()
+            .toString() shouldBe "https://docs.gradle.org/7.6.1/javadoc/package-list"
+        }
+      }
+    }
+  }
+})
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/DokkaExternalDocumentationLinkSpecTest.kt b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/DokkaExternalDocumentationLinkSpecTest.kt
new file mode 100644
index 00000000..28fb2b83
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/DokkaExternalDocumentationLinkSpecTest.kt
@@ -0,0 +1,102 @@
+package org.jetbrains.dokka.dokkatoo.dokka.parameters
+
+import org.jetbrains.dokka.dokkatoo.DokkatooExtension
+import org.jetbrains.dokka.dokkatoo.DokkatooPlugin
+import org.jetbrains.dokka.dokkatoo.utils.create_
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.datatest.WithDataTestName
+import io.kotest.datatest.withData
+import io.kotest.matchers.shouldBe
+import org.gradle.kotlin.dsl.*
+import org.gradle.testfixtures.ProjectBuilder
+
+
+class DokkaExternalDocumentationLinkSpecTest : FunSpec({
+
+  context("expect url can be set") {
+    test("using a string") {
+      val actual = createExternalDocLinkSpec {
+        url("https://github.com/adamko-dev/dokkatoo/")
+      }
+
+      actual.url.get().toString() shouldBe "https://github.com/adamko-dev/dokkatoo/"
+    }
+
+    test("using a string-provider") {
+      val actual = createExternalDocLinkSpec {
+        url(project.provider { "https://github.com/adamko-dev/dokkatoo/" })
+      }
+
+      actual.url.get().toString() shouldBe "https://github.com/adamko-dev/dokkatoo/"
+    }
+  }
+
+  context("expect packageListUrl can be set") {
+    test("using a string") {
+      val actual = createExternalDocLinkSpec {
+        packageListUrl("https://github.com/adamko-dev/dokkatoo/")
+      }
+
+      actual.packageListUrl.get().toString() shouldBe "https://github.com/adamko-dev/dokkatoo/"
+    }
+
+    test("using a string-provider") {
+      val actual = createExternalDocLinkSpec {
+        packageListUrl(project.provider { "https://github.com/adamko-dev/dokkatoo/" })
+      }
+
+      actual.packageListUrl.get().toString() shouldBe "https://github.com/adamko-dev/dokkatoo/"
+    }
+  }
+
+  context("expect packageList defaults to url+package-list") {
+    data class TestCase(
+      val actualUrl: String,
+      val expected: String,
+      val testName: String,
+    ) : WithDataTestName {
+      override fun dataTestName(): String = testName
+    }
+
+    withData(
+      TestCase(
+        testName = "non-empty path, with trailing slash",
+        actualUrl = "https://github.com/adamko-dev/dokkatoo/",
+        expected = "https://github.com/adamko-dev/dokkatoo/package-list",
+      ),
+      TestCase(
+        testName = "non-empty path, without trailing slash",
+        actualUrl = "https://github.com/adamko-dev/dokkatoo",
+        expected = "https://github.com/adamko-dev/dokkatoo/package-list",
+      ),
+      TestCase(
+        testName = "empty path, with trailing slash",
+        actualUrl = "https://github.com/",
+        expected = "https://github.com/package-list",
+      ),
+      TestCase(
+        testName = "empty path, without trailing slash",
+        actualUrl = "https://github.com",
+        expected = "https://github.com/package-list",
+      )
+    ) { (actualUrl, expected) ->
+      val actual = createExternalDocLinkSpec { url(actualUrl) }
+      actual.packageListUrl.get().toString() shouldBe expected
+    }
+  }
+})
+
+private val project = ProjectBuilder.builder().build().also { project ->
+  project.plugins.apply(type = DokkatooPlugin::class)
+}
+
+private fun createExternalDocLinkSpec(
+  configure: DokkaExternalDocumentationLinkSpec.() -> Unit
+): DokkaExternalDocumentationLinkSpec {
+
+  val dssContainer = project.extensions.getByType<DokkatooExtension>().dokkatooSourceSets
+
+  return dssContainer.create_("test" + dssContainer.size)
+    .externalDocumentationLinks
+    .create("testLink", configure)
+}
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/DokkaSourceLinkSpecTest.kt b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/DokkaSourceLinkSpecTest.kt
new file mode 100644
index 00000000..f3171a57
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/DokkaSourceLinkSpecTest.kt
@@ -0,0 +1,58 @@
+package org.jetbrains.dokka.dokkatoo.dokka.parameters
+
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.engine.spec.tempdir
+import io.kotest.matchers.shouldBe
+import org.gradle.api.Project
+import org.gradle.api.provider.Provider
+import org.gradle.kotlin.dsl.*
+import org.gradle.testfixtures.ProjectBuilder
+
+class DokkaSourceLinkSpecTest : FunSpec({
+  val project = ProjectBuilder.builder().build()
+
+  context("expect localDirectoryPath") {
+    test("is the invariantSeparatorsPath of localDirectory") {
+      val tempDir = tempdir()
+
+      val actual = project.createDokkaSourceLinkSpec {
+        localDirectory.set(tempDir)
+      }
+
+      actual.localDirectoryPath2.get() shouldBe tempDir.invariantSeparatorsPath
+    }
+  }
+
+
+  context("expect remoteUrl can be set") {
+    test("using a string") {
+      val actual = project.createDokkaSourceLinkSpec {
+        remoteUrl("https://github.com/adamko-dev/dokkatoo/")
+      }
+
+      actual.remoteUrl.get().toString() shouldBe "https://github.com/adamko-dev/dokkatoo/"
+    }
+
+    test("using a string-provider") {
+      val actual = project.createDokkaSourceLinkSpec {
+        remoteUrl(project.provider { "https://github.com/adamko-dev/dokkatoo/" })
+      }
+
+      actual.remoteUrl.get().toString() shouldBe "https://github.com/adamko-dev/dokkatoo/"
+    }
+  }
+}) {
+
+  /** Re-implement [DokkaSourceLinkSpec] to make [localDirectoryPath] accessible in tests */
+  abstract class DokkaSourceLinkSpec2 : DokkaSourceLinkSpec() {
+    val localDirectoryPath2: Provider<String>
+      get() = super.localDirectoryPath
+  }
+
+  companion object {
+    private fun Project.createDokkaSourceLinkSpec(
+      configure: DokkaSourceLinkSpec.() -> Unit
+    ): DokkaSourceLinkSpec2 =
+      objects.newInstance(DokkaSourceLinkSpec2::class).apply(configure)
+  }
+}
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/KotlinPlatformTest.kt b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/KotlinPlatformTest.kt
new file mode 100644
index 00000000..c921df9a
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/KotlinPlatformTest.kt
@@ -0,0 +1,37 @@
+package org.jetbrains.dokka.dokkatoo.dokka.parameters
+
+import org.jetbrains.dokka.dokkatoo.dokka.parameters.KotlinPlatform.Companion.dokkaType
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.inspectors.shouldForAll
+import io.kotest.matchers.collections.shouldBeIn
+import io.kotest.matchers.shouldBe
+import org.jetbrains.dokka.Platform
+
+class KotlinPlatformTest : FunSpec({
+
+  test("should have same default as Dokka type") {
+    KotlinPlatform.DEFAULT.dokkaType shouldBe Platform.DEFAULT
+  }
+
+  test("Dokka platform should have equivalent KotlinPlatform") {
+
+    Platform.values().shouldForAll { dokkaPlatform ->
+      dokkaPlatform shouldBeIn KotlinPlatform.values.map { it.dokkaType }
+    }
+  }
+
+  test("platform strings should map to same KotlinPlatform and Platform") {
+    listOf(
+      "androidJvm",
+      "android",
+      "metadata",
+      "jvm",
+      "js",
+      "wasm",
+      "native",
+      "common",
+    ).shouldForAll {
+      Platform.fromString(it) shouldBe KotlinPlatform.fromString(it).dokkaType
+    }
+  }
+})
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/VisibilityModifierTest.kt b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/VisibilityModifierTest.kt
new file mode 100644
index 00000000..ca5ad49a
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/VisibilityModifierTest.kt
@@ -0,0 +1,17 @@
+package org.jetbrains.dokka.dokkatoo.dokka.parameters
+
+import org.jetbrains.dokka.dokkatoo.dokka.parameters.VisibilityModifier.Companion.dokkaType
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.inspectors.shouldForAll
+import io.kotest.inspectors.shouldForOne
+import io.kotest.matchers.shouldBe
+import org.jetbrains.dokka.DokkaConfiguration
+
+class VisibilityModifierTest : FunSpec({
+
+  test("DokkaConfiguration.Visibility should have equivalent VisibilityModifier") {
+    DokkaConfiguration.Visibility.values().shouldForAll { dokkaVisibility ->
+      VisibilityModifier.entries.map { it.dokkaType }.shouldForOne { it shouldBe dokkaVisibility }
+    }
+  }
+})
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/builders/DokkaModuleDescriptionBuilderTest.kt b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/builders/DokkaModuleDescriptionBuilderTest.kt
new file mode 100644
index 00000000..ff442663
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/builders/DokkaModuleDescriptionBuilderTest.kt
@@ -0,0 +1,7 @@
+package org.jetbrains.dokka.dokkatoo.dokka.parameters.builders
+
+import io.kotest.core.spec.style.FunSpec
+
+class DokkaModuleDescriptionBuilderTest : FunSpec({
+
+})
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/builders/DokkaParametersBuilderTest.kt b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/builders/DokkaParametersBuilderTest.kt
new file mode 100644
index 00000000..66918194
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/builders/DokkaParametersBuilderTest.kt
@@ -0,0 +1,7 @@
+package org.jetbrains.dokka.dokkatoo.dokka.parameters.builders
+
+import io.kotest.core.spec.style.FunSpec
+
+class DokkaParametersBuilderTest : FunSpec({
+
+})
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/builders/DokkaSourceSetBuilderTest.kt b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/builders/DokkaSourceSetBuilderTest.kt
new file mode 100644
index 00000000..bb4bf8a7
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/builders/DokkaSourceSetBuilderTest.kt
@@ -0,0 +1,198 @@
+package org.jetbrains.dokka.dokkatoo.dokka.parameters.builders
+
+import org.jetbrains.dokka.dokkatoo.DokkatooExtension
+import org.jetbrains.dokka.dokkatoo.DokkatooPlugin
+import org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaSourceSetSpec
+import org.jetbrains.dokka.dokkatoo.utils.all_
+import org.jetbrains.dokka.dokkatoo.utils.create_
+import org.jetbrains.dokka.dokkatoo.utils.shouldContainAll
+import org.jetbrains.dokka.dokkatoo.utils.sourceLink_
+import io.kotest.assertions.throwables.shouldThrow
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.engine.spec.tempdir
+import io.kotest.inspectors.shouldForAll
+import io.kotest.matchers.collections.shouldBeSingleton
+import io.kotest.matchers.equals.shouldNotBeEqual
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.string.shouldContain
+import java.io.File
+import java.net.URI
+import org.gradle.api.Project
+import org.gradle.api.file.Directory
+import org.gradle.api.internal.provider.MissingValueException
+import org.gradle.kotlin.dsl.*
+import org.gradle.testfixtures.ProjectBuilder
+
+class DokkaSourceSetBuilderTest : FunSpec({
+
+  context("when building a ExternalDocumentationLinkSpec") {
+    val project = createProject()
+
+    test("expect url is required") {
+      val sourceSetSpec = project.createDokkaSourceSetSpec("test1") {
+        externalDocumentationLinks.create_("TestLink") {
+          url.set(null as URI?)
+          packageListUrl("https://github.com/adamko-dev/dokkatoo/")
+        }
+      }
+
+      val caughtException = shouldThrow<MissingValueException> {
+        DokkaSourceSetBuilder.buildAll(setOf(sourceSetSpec))
+      }
+
+      caughtException.message shouldContain "Cannot query the value of property 'url' because it has no value available"
+    }
+
+    test("expect packageListUrl is required") {
+      val sourceSetSpec = project.createDokkaSourceSetSpec("test2") {
+        externalDocumentationLinks.create_("TestLink") {
+          url("https://github.com/adamko-dev/dokkatoo/")
+          packageListUrl.convention(null as URI?)
+          packageListUrl.set(null as URI?)
+        }
+      }
+
+      val caughtException = shouldThrow<MissingValueException> {
+        DokkaSourceSetBuilder.buildAll(setOf(sourceSetSpec))
+      }
+
+      caughtException.message shouldContain "Cannot query the value of property 'packageListUrl' because it has no value available"
+    }
+
+    test("expect null when not enabled") {
+      val sourceSetSpec = project.createDokkaSourceSetSpec("test3")
+      val linkSpec = sourceSetSpec.externalDocumentationLinks.create_("TestLink") {
+        url("https://github.com/adamko-dev/dokkatoo/")
+        packageListUrl("https://github.com/adamko-dev/dokkatoo/")
+        enabled.set(false)
+      }
+
+      DokkaSourceSetBuilder.buildAll(setOf(sourceSetSpec)).shouldBeSingleton { sourceSet ->
+        sourceSet.externalDocumentationLinks.shouldForAll { link ->
+          link.url shouldNotBeEqual linkSpec.url.get().toURL()
+          link.packageListUrl shouldNotBeEqual linkSpec.packageListUrl.get().toURL()
+        }
+      }
+    }
+  }
+
+
+  context("when DokkaSourceLinkSpec is built") {
+    val project = createProject()
+
+    test("expect built object contains all properties") {
+      val tempDir = tempdir()
+
+      val sourceSetSpec = project.createDokkaSourceSetSpec("testAllProperties") {
+        sourceLink_ {
+          localDirectory.set(tempDir)
+          remoteUrl("https://github.com/adamko-dev/dokkatoo/")
+          remoteLineSuffix.set("%L")
+        }
+      }
+
+      val sourceSet = DokkaSourceSetBuilder.buildAll(setOf(sourceSetSpec)).single()
+
+      sourceSet.sourceLinks.shouldBeSingleton { sourceLink ->
+        sourceLink.remoteUrl shouldBe URI("https://github.com/adamko-dev/dokkatoo/").toURL()
+        sourceLink.localDirectory shouldBe tempDir.invariantSeparatorsPath
+        sourceLink.remoteLineSuffix shouldBe "%L"
+      }
+    }
+
+    test("expect localDirectory is required") {
+      val sourceSetSpec = project.createDokkaSourceSetSpec("testLocalDirRequired") {
+        sourceLink_ {
+          remoteUrl("https://github.com/adamko-dev/dokkatoo/")
+          remoteLineSuffix.set("%L")
+        }
+      }
+
+      sourceSetSpec.sourceLinks.all_ {
+        localDirectory.convention(null as Directory?)
+        localDirectory.set(null as File?)
+      }
+
+      val caughtException = shouldThrow<MissingValueException> {
+        DokkaSourceSetBuilder.buildAll(setOf(sourceSetSpec))
+      }
+
+      caughtException.message.shouldContainAll(
+        "Cannot query the value of this provider because it has no value available",
+        "The value of this provider is derived from",
+        "property 'localDirectory'",
+      )
+    }
+
+    test("expect localDirectory is an invariantSeparatorsPath") {
+      val tempDir = tempdir()
+
+      val sourceSetSpec = project.createDokkaSourceSetSpec("testLocalDirPath") {
+        sourceLink_ {
+          localDirectory.set(tempDir)
+          remoteUrl("https://github.com/adamko-dev/dokkatoo/")
+          remoteLineSuffix.set(null as String?)
+        }
+      }
+
+      val link = DokkaSourceSetBuilder.buildAll(setOf(sourceSetSpec))
+        .single()
+        .sourceLinks
+        .single()
+
+      link.localDirectory shouldBe tempDir.invariantSeparatorsPath
+    }
+
+    test("expect remoteUrl is required") {
+      val sourceSetSpec = project.createDokkaSourceSetSpec("testRemoteUrlRequired") {
+        sourceLink_ {
+          localDirectory.set(tempdir())
+          remoteUrl.set(project.providers.provider { null })
+          remoteLineSuffix.set("%L")
+        }
+      }
+
+      val caughtException = shouldThrow<MissingValueException> {
+        DokkaSourceSetBuilder.buildAll(setOf(sourceSetSpec))
+      }
+
+      caughtException.message shouldContain "Cannot query the value of property 'remoteUrl' because it has no value available"
+    }
+
+    test("expect remoteLineSuffix is optional") {
+      val tempDir = tempdir()
+
+      val sourceSetSpec = project.createDokkaSourceSetSpec("testRemoteLineSuffixOptional") {
+        sourceLink_ {
+          localDirectory.set(tempDir)
+          remoteUrl("https://github.com/adamko-dev/dokkatoo/")
+          remoteLineSuffix.set(project.providers.provider { null })
+        }
+      }
+
+      val sourceSet = DokkaSourceSetBuilder.buildAll(setOf(sourceSetSpec)).single()
+
+      sourceSet.sourceLinks.shouldBeSingleton { sourceLink ->
+        sourceLink.remoteUrl shouldBe URI("https://github.com/adamko-dev/dokkatoo/").toURL()
+        sourceLink.localDirectory shouldBe tempDir.invariantSeparatorsPath
+        sourceLink.remoteLineSuffix shouldBe null
+      }
+    }
+  }
+})
+
+private fun createProject(): Project {
+  val project = ProjectBuilder.builder().build()
+  project.plugins.apply(type = DokkatooPlugin::class)
+  return project
+}
+
+private fun Project.createDokkaSourceSetSpec(
+  name: String,
+  configure: DokkaSourceSetSpec.() -> Unit = {}
+): DokkaSourceSetSpec {
+  return extensions
+    .getByType<DokkatooExtension>()
+    .dokkatooSourceSets
+    .create_(name, configure)
+}