Fix external documentation link default values (#3812)

KT-70908
Kotlin · Oct 1, 2024 · 29593f7 · 29593f7
1 parent 5b2fd99
commit 29593f7
Show file tree

Hide file tree

Showing 3 changed files with 31 additions and 6 deletions.
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt
@@ -229,7 +229,7 @@ constructor(
                 }
 
                 maybeCreate("jdk") {
-                    enabled.convention(this@dss.enableJdkDocumentationLink)
+                    enabled.set(this@dss.enableJdkDocumentationLink)
                     url(this@dss.jdkVersion.map { jdkVersion ->
                         when {
                             jdkVersion < 11 -> "https://docs.oracle.com/javase/${jdkVersion}/docs/api/"
@@ -245,17 +245,17 @@ constructor(
                 }
 
                 maybeCreate("kotlinStdlib") {
-                    enabled.convention(this@dss.enableKotlinStdLibDocumentationLink)
+                    enabled.set(this@dss.enableKotlinStdLibDocumentationLink)
                     url("https://kotlinlang.org/api/latest/jvm/stdlib/")
                 }
 
                 maybeCreate("androidSdk") {
-                    enabled.convention(this@dss.enableAndroidDocumentationLink)
+                    enabled.set(this@dss.enableAndroidDocumentationLink)
                     url("https://developer.android.com/reference/kotlin/")
                 }
 
                 maybeCreate("androidX") {
-                    enabled.convention(this@dss.enableAndroidDocumentationLink)
+                    enabled.set(this@dss.enableAndroidDocumentationLink)
                     url("https://developer.android.com/reference/kotlin/")
                     packageListUrl("https://developer.android.com/reference/kotlin/androidx/package-list")
                 }

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceSetSpec.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceSetSpec.kt
@@ -311,9 +311,11 @@ constructor(
      * Whether to generate external documentation links for Android SDK API reference when
      * declarations from it are used.
      *
-     * Only relevant in Android projects, ignored otherwise.
+     * Only relevant in Android projects, and will be automatically disabled otherwise.
      *
-     * Default is `false`, meaning links will not be generated.
+     * The default value is automatically determined.
+     * If [analysisPlatform] is set to [KotlinPlatform.AndroidJVM], then the value will be `true`.
+     * Otherwise, the value defaults to `false`.
      *
      * @see externalDocumentationLinks
      */

diff --git a/dokka-runners/dokka-gradle-plugin/src/test/kotlin/DokkaPluginTest.kt b/dokka-runners/dokka-gradle-plugin/src/test/kotlin/DokkaPluginTest.kt
@@ -86,6 +86,29 @@ class DokkaPluginTest : FunSpec({
                     gradleDocLink.packageListUrl.get()
                         .toString() shouldBe "https://docs.gradle.org/7.6.1/javadoc/package-list"
                 }
+
+                test("externalDocumentationLinks should be enabled by default") {
+                    val fooLink = testSourceSet.externalDocumentationLinks.create("foo")
+                    fooLink.enabled.orNull shouldBe true
+                }
+
+                test("kotlinStdlib externalDocumentationLink should be disabled when DokkaSourceSetSpec.enableKotlinStdLibDocumentationLink is disabled") {
+                    testSourceSet.enableKotlinStdLibDocumentationLink.set(false)
+                    val kotlinStdlib = testSourceSet.externalDocumentationLinks.getByName("kotlinStdlib")
+                    kotlinStdlib.enabled.orNull shouldBe false
+                }
+
+                context("Android externalDocumentationLinks should be disabled when DokkaSourceSetSpec.enableAndroidDocumentationLink is disabled") {
+                    testSourceSet.enableAndroidDocumentationLink.set(false)
+                    test("androidSdk") {
+                        val androidSdk = testSourceSet.externalDocumentationLinks.getByName("androidSdk")
+                        androidSdk.enabled.orNull shouldBe false
+                    }
+                    test("androidX") {
+                        val androidX = testSourceSet.externalDocumentationLinks.getByName("androidX")
+                        androidX.enabled.orNull shouldBe false
+                    }
+                }
             }
 
             context("perPackageOptions") {