tidy up external doc links helpers (#48)

* tidy up external doc links helpers - rename no[Jdk/Android/Kotlin]Link boolean helpers to enable[Jdk/Android/Kotlin]DocumentationLink to match naming convention - deprecate externalDocumentationLink() helper function, since the helpers have been moved and links require a unique name * formatting
adamko-dev · Apr 8, 2023 · a6a5787 · a6a5787
1 parent 7e33a1f
commit a6a5787
Show file tree

Hide file tree

Showing 5 changed files with 101 additions and 45 deletions.
diff --git a/modules/dokkatoo-plugin/api/dokkatoo-plugin.api b/modules/dokkatoo-plugin/api/dokkatoo-plugin.api
@@ -236,6 +236,9 @@ public abstract class dev/adamko/dokkatoo/dokka/parameters/DokkaSourceSetSpec :
 	public abstract fun getDependentSourceSets ()Lorg/gradle/api/NamedDomainObjectContainer;
 	public abstract fun getDisplayName ()Lorg/gradle/api/provider/Property;
 	public abstract fun getDocumentedVisibilities ()Lorg/gradle/api/provider/SetProperty;
+	public abstract fun getEnableAndroidDocumentationLink ()Lorg/gradle/api/provider/Property;
+	public abstract fun getEnableJdkDocumentationLink ()Lorg/gradle/api/provider/Property;
+	public abstract fun getEnableKotlinStdLibDocumentationLink ()Lorg/gradle/api/provider/Property;
 	public abstract fun getExternalDocumentationLinks ()Lorg/gradle/api/NamedDomainObjectContainer;
 	public abstract fun getIncludes ()Lorg/gradle/api/file/ConfigurableFileCollection;
 	public abstract fun getJdkVersion ()Lorg/gradle/api/provider/Property;

diff --git a/modules/dokkatoo-plugin/src/main/kotlin/DokkatooBasePlugin.kt b/modules/dokkatoo-plugin/src/main/kotlin/DokkatooBasePlugin.kt
@@ -158,9 +158,18 @@ constructor(
       )
       documentedVisibilities.convention(setOf(VisibilityModifier.PUBLIC))
       jdkVersion.convention(8)
+
+      @Suppress("DEPRECATION")
       noAndroidSdkLink.convention(true)
+      @Suppress("DEPRECATION")
       noJdkLink.convention(false)
+      @Suppress("DEPRECATION")
       noStdlibLink.convention(false)
+
+      enableKotlinStdLibDocumentationLink.convention(true)
+      enableJdkDocumentationLink.convention(true)
+      enableAndroidDocumentationLink.convention(false)
+
       reportUndocumented.convention(false)
       skipDeprecated.convention(false)
       skipEmptyPackages.convention(true)
@@ -191,7 +200,7 @@ constructor(
         }
 
         create("jdk") {
-          enabled.convention(!this@dss.noJdkLink)
+          enabled.convention(this@dss.enableJdkDocumentationLink)
           url(this@dss.jdkVersion.map { jdkVersion ->
             when {
               jdkVersion < 11 -> "https://docs.oracle.com/javase/${jdkVersion}/docs/api/"
@@ -205,16 +214,19 @@ constructor(
             }
           })
         }
+
         create("kotlinStdlib") {
-          enabled.convention(!this@dss.noStdlibLink)
+          enabled.convention(this@dss.enableKotlinStdLibDocumentationLink)
           url("https://kotlinlang.org/api/latest/jvm/stdlib/")
         }
+
         create("androidSdk") {
-          enabled.convention(!this@dss.noAndroidSdkLink)
+          enabled.convention(this@dss.enableAndroidDocumentationLink)
           url("https://developer.android.com/reference/kotlin/")
         }
+
         create("androidX") {
-          enabled.convention(!this@dss.noAndroidSdkLink)
+          enabled.convention(this@dss.enableAndroidDocumentationLink)
           url("https://developer.android.com/reference/kotlin/")
           packageListUrl("https://developer.android.com/reference/kotlin/androidx/package-list")
         }

diff --git a/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/DokkaParametersKxs.kt b/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/DokkaParametersKxs.kt
@@ -88,8 +88,8 @@ data class DokkaParametersKxs(
     val externalDocumentationLinks: Set<ExternalDocumentationLinkKxs>,
     val languageVersion: String? = null,
     val apiVersion: String? = null,
-    val noStdlibLink: Boolean,
-    val noJdkLink: Boolean,
+    val enableKotlinStdLibDocumentationLink: Boolean,
+    val enableJdkDocumentationLink: Boolean,
     val suppressedFiles: Set<File>,
     val analysisPlatform: Platform,
     val documentedVisibilities: Set<DokkaConfiguration.Visibility>,
@@ -117,8 +117,8 @@ data class DokkaParametersKxs(
         ),
         languageVersion = languageVersion,
         apiVersion = apiVersion,
-        noStdlibLink = noStdlibLink,
-        noJdkLink = noJdkLink,
+        noStdlibLink = !enableKotlinStdLibDocumentationLink,
+        noJdkLink = !enableJdkDocumentationLink,
         suppressedFiles = suppressedFiles,
         analysisPlatform = analysisPlatform,
         documentedVisibilities = documentedVisibilities,

diff --git a/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/DokkaSourceSetSpec.kt b/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/DokkaSourceSetSpec.kt
@@ -129,8 +129,6 @@ constructor(
    * Among other things, this information is needed to resolve
    * [expect/actual](https://kotlinlang.org/docs/multiplatform-connect-to-apis.html) declarations.
    *
-   * Prefer using [dependsOn] function to append dependent source sets to this list.
-   *
    * By default, the values are deduced from information provided by the Kotlin Gradle plugin.
    */
   @get:Nested
@@ -160,7 +158,7 @@ constructor(
 
   /**
    * List of directories or files that contain sample functions which are referenced via
-   * [@sample](https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier) KDoc tag.
+   * [`@sample`](https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier) KDoc tag.
    */
   @get:InputFiles
   @get:Optional
@@ -171,8 +169,6 @@ constructor(
    * Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs
    * after they have been filtered by [documentedVisibilities].
    *
-   * This setting works well with [AbstractDokkaTask.failOnWarning].
-   *
    * Can be overridden for a specific package by setting [DokkaPackageOptionsSpec.reportUndocumented].
    *
    * Default is `false`.
@@ -260,39 +256,60 @@ constructor(
   abstract val suppressGeneratedFiles: Property<Boolean>
 
   /**
-   * Whether to generate external documentation links that lead to API reference
-   * documentation for Kotlin's standard library when declarations from it are used.
+   * Whether to generate external documentation links that lead to API reference documentation for
+   * Kotlin's standard library when declarations from it are used.
+   *
+   * Default is `true`, meaning links will be generated.
    *
-   * Default is `false`, meaning links will be generated.
+   * @see externalDocumentationLinks
    */
   @get:Input
-  abstract val noStdlibLink: Property<Boolean>
+  abstract val enableKotlinStdLibDocumentationLink: Property<Boolean>
 
   /**
-   * Whether to generate external documentation links to JDK's Javadocs
-   * when declarations from it are used.
+   * Whether to generate external documentation links to JDK's Javadocs when declarations from it
+   * are used.
    *
    * The version of JDK Javadocs is determined by [jdkVersion] property.
    *
-   * Default is `false`, meaning links will be generated.
+   * Default is `true`, meaning links will be generated.
+   *
+   * @see externalDocumentationLinks
    */
   @get:Input
-  abstract val noJdkLink: Property<Boolean>
+  abstract val enableJdkDocumentationLink: Property<Boolean>
 
   /**
-   * Whether to generate external documentation links for Android SDK API reference
-   * when declarations from it are used.
+   * Whether to generate external documentation links for Android SDK API reference when
+   * declarations from it are used.
    *
    * Only relevant in Android projects, ignored otherwise.
    *
-   * Default is `false`, meaning links will be generated.
+   * Default is `false`, meaning links will not be generated.
+   *
+   * @see externalDocumentationLinks
    */
   @get:Input
+  abstract val enableAndroidDocumentationLink: Property<Boolean>
+
+  /** @see enableKotlinStdLibDocumentationLink */
+  @get:Internal
+  @Deprecated("Replaced with enableKotlinStdLibDocumentationLink to match naming conventions - note that the boolean is inverted")
+  abstract val noStdlibLink: Property<Boolean>
+
+  /** @see enableJdkDocumentationLink */
+  @get:Internal
+  @Deprecated("Replaced with enableJdkDocumentationLink to match naming conventions - note that the boolean is inverted")
+  abstract val noJdkLink: Property<Boolean>
+
+  /** @see enableAndroidDocumentationLink */
+  @get:Internal
+  @Deprecated("Replaced with enableAndroidDocumentationLink to match naming conventions - note that the boolean is inverted")
   abstract val noAndroidSdkLink: Property<Boolean>
 
   /**
    * [Kotlin language version](https://kotlinlang.org/docs/compatibility-modes.html)
-   * used for setting up analysis and [@sample](https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier)
+   * used for setting up analysis and [`@sample`](https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier)
    * environment.
    *
    * By default, the latest language version available to Dokka's embedded compiler will be used.
@@ -303,7 +320,7 @@ constructor(
 
   /**
    * [Kotlin API version](https://kotlinlang.org/docs/compatibility-modes.html)
-   * used for setting up analysis and [@sample](https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier)
+   * used for setting up analysis and [`@sample`](https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier)
    * environment.
    *
    * By default, it will be deduced from [languageVersion].
@@ -350,25 +367,44 @@ constructor(
     )
   }
 
-  /**
-   * Action for configuring external documentation links, appending to [externalDocumentationLinks].
-   *
-   * @see DokkaExternalDocumentationLinkSpec
-   */
+  /** @see externalDocumentationLinks */
+  @Deprecated(
+    externalDocumentationLinkDeprecationMessage,
+    ReplaceWith("externalDocumentationLinks.create(\"...\", action)"),
+  )
   fun externalDocumentationLink(action: Action<in DokkaExternalDocumentationLinkSpec>) {
-    externalDocumentationLinks.add(
-      objects.newInstance(DokkaExternalDocumentationLinkSpec::class).also {
-        action.execute(it)
-      }
-    )
+    externalDocumentationLinks.create("...", action)
   }
 
-  /** Convenient override to **append** external documentation links to [externalDocumentationLinks]. */
+  /** @see externalDocumentationLinks */
+  @Deprecated(
+    externalDocumentationLinkDeprecationMessage,
+    ReplaceWith(
+      "externalDocumentationLinks.create(TODO(\"<unique name>\")) {\n" +
+          "  this.url(url)\n" +
+          "  if (packageListUrl != null) this.packageListUrl(packageListUrl)\n" +
+          "}"
+    ),
+  )
   fun externalDocumentationLink(url: String, packageListUrl: String? = null) {
-    externalDocumentationLink(URL(url), packageListUrl = packageListUrl?.let(::URL))
+    externalDocumentationLinks.create("...") {
+      url(url)
+      if (packageListUrl != null) {
+        packageListUrl(packageListUrl)
+      }
+    }
   }
 
-  /** Convenient override to **append** external documentation links to [externalDocumentationLinks]. */
+  /** @see externalDocumentationLinks */
+  @Deprecated(
+    externalDocumentationLinkDeprecationMessage,
+    ReplaceWith(
+      "externalDocumentationLinks.create(TODO(\"<unique name>\")) {\n" +
+          "  this.url.set(url)\n" +
+          "  if (packageListUrl != null) this.packageListUrl.set(packageListUrl)\n" +
+          "}"
+    ),
+  )
   fun externalDocumentationLink(url: URL, packageListUrl: URL? = null) {
     externalDocumentationLinks.add(
       objects.newInstance(DokkaExternalDocumentationLinkSpec::class).also {
@@ -403,11 +439,16 @@ constructor(
       externalDocumentationLinks = externalDocumentationLinks,
       languageVersion = languageVersion.orNull,
       apiVersion = apiVersion.orNull,
-      noStdlibLink = noStdlibLink.get(),
-      noJdkLink = noJdkLink.get(),
+      enableKotlinStdLibDocumentationLink = enableKotlinStdLibDocumentationLink.get(),
+      enableJdkDocumentationLink = enableJdkDocumentationLink.get(),
       suppressedFiles = suppressedFiles.files,
       analysisPlatform = analysisPlatform.get().dokkaType,
       documentedVisibilities = documentedVisibilities.get().mapToSet { it.dokkaType },
     )
   }
+
+  private companion object {
+    private const val externalDocumentationLinkDeprecationMessage =
+      "DokkaExternalDocumentationLinkSpecs require a unique name. Helper functions for creating an external doc link have been moved to DokkaExternalDocumentationLinkSpec. Use `externalDocumentationLinks.create(...) { ... } instead."
+  }
 }
diff --git a/modules/dokkatoo-plugin/src/test/kotlin/DokkatooPluginTest.kt b/modules/dokkatoo-plugin/src/test/kotlin/DokkatooPluginTest.kt
@@ -77,13 +77,13 @@ class DokkatooPluginTest : FunSpec({
       context("JDK external documentation link") {
         val jdkLink = testSourceSet.externalDocumentationLinks.getByName("jdk")
 
-        test("when noJdkLink is true, expect jdk link is disabled") {
-          testSourceSet.noJdkLink.set(true)
+        test("when enableJdkDocumentationLink is false, expect jdk link is disabled") {
+          testSourceSet.enableJdkDocumentationLink.set(false)
           jdkLink.enabled.get() shouldBe false
         }
 
-        test("when noJdkLink is false, expect jdk link is enabled") {
-          testSourceSet.noJdkLink.set(false)
+        test("when enableJdkDocumentationLink is true, expect jdk link is enabled") {
+          testSourceSet.enableJdkDocumentationLink.set(true)
           jdkLink.enabled.get() shouldBe true
         }