Upgrade Dokka to 2.2.0 and migrate to Gradle plugin v2 DSL (#3731)

Upgrades Dokka from 1.8.10 to 2.2.0 and migrates to the v2 Gradle plugin
DSL. Upgrades Kotlin version just for the Dokka plugin (required by v2).

This is a first step towards AGP 9 since Dokka 1.x was blocking that.

## Changes

- Dokka bumped to 2.2.0
- Config adapted to use the `dokka` extension and preserve existng
contents
- CI docs job now runs `./gradlew :dokkaGenerate` rather than
`dokkaHtmlMultiModule`.
- dokka-hide-internal: Dokka 2.2's K2 analysis needs a newer Kotlin
stdlib at test runtime; added as testRuntimeOnly, version tracked in the
catalog (dokkaAnalysisKotlin).
- Fixed a pre-existing broken source link base (public/src/main/java to
purchases/src/main/java).

## Verification

The docs CI job only runs on release tags, so verified locally:

- :dokkaGenerate output diffed against a Dokka 1.8.10 build from the
merge base: identical module layout and deep-link URLs; CEC and
paywalls.components suppressions, README landing page, and hide-internal
filtering all intact. Only additions are enum entries pages and a ui-kit
static assets dir from the new Dokka HTML format.
- dokka-hide-internal tests pass against the 2.2.0 engine.

  
Ref: #2618


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes the release docs pipeline and a major Dokka upgrade; SDK
runtime is unaffected, but incomplete v2 config or test classpath quirks
could break CI doc generation or `dokka-hide-internal` tests.
> 
> **Overview**
> **Dokka** is upgraded from **1.8.10** to **2.2.0** and doc generation
moves to the **Gradle plugin v2** model (`dokka { }` DSL,
`:dokkaGenerate` instead of `dokkaHtmlMultiModule` /
`dokkaHtmlPartial`).
> 
> The **root** build applies the `base` plugin, drops the custom `clean`
task and the old `DokkaMultiModuleTask` hook, and instead auto-registers
every subproject that applies Dokka into the root `dokka` dependency
graph. HTML output stays under `docs/${VERSION_NAME}` with `README.md`
included. **CI** `docs-deploy` runs `./gradlew :dokkaGenerate`.
> 
> **`purchases`** and **`ui/revenuecatui`** use top-level `dokka {
dokkaSourceSets { ... } }` with v2 APIs (`dependentSourceSets`,
`externalDocumentationLinks.register`, `remoteUrl(...)`).
**`purchases`** extracts shared source-set settings into
`configureDocumentedSourceSet()` and fixes the `src/main/java` GitHub
source link path.
> 
> **`dokka-hide-internal`** adds `analysis-kotlin-symbols` and Kotlin
**2.2.0** stdlib as **testRuntimeOnly** so Dokka 2.2 K2 analysis works
while the repo still compiles on Kotlin **2.0.21**.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
c8b1585. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: AlvaroBrey

.circleci/config.yml

@@ -375,7 +375,7 @@ jobs:
       - android/restore_build_cache
       - run:
           name: Dokka
-          command: ./gradlew dokkaHtmlMultiModule
+          command: ./gradlew :dokkaGenerate
       - android/save_gradle_cache
       - android/save_build_cache
       - run:

build.gradle.kts

@@ -1,4 +1,5 @@
 plugins {
+    base
     alias(libs.plugins.mavenPublish) apply false
     alias(libs.plugins.android.application) apply false
     alias(libs.plugins.android.library) apply false
@@ -27,8 +28,20 @@ dependencies {
     detektPlugins(project(":detekt-rules"))
 }
 
-tasks.register<Delete>("clean") {
-    delete(rootProject.layout.buildDirectory)
+// Aggregate docs from every module that applies the Dokka plugin (currently done by revenuecat-public-library),
+// so new library modules are documented without having to remember to list them here.
+val dokkaPluginId = libs.plugins.dokka.get().pluginId
+subprojects {
+    plugins.withId(dokkaPluginId) {
+        rootProject.dependencies.add("dokka", project)
+    }
+}
+
+dokka {
+    dokkaPublications.html {
+        outputDirectory.set(file("docs/${project.property("VERSION_NAME")}"))
+        includes.from("README.md")
+    }
 }
 
 tasks.register<io.gitlab.arturbosch.detekt.Detekt>("detektAll") {
@@ -70,8 +83,3 @@ tasks.register<io.gitlab.arturbosch.detekt.DetektCreateBaselineTask>("detektAllB
         "**/testCustomEntitlementComputation/**/*.kt",
     )
 }
-
-tasks.named<org.jetbrains.dokka.gradle.DokkaMultiModuleTask>("dokkaHtmlMultiModule") {
-    outputDirectory.set(file("docs/${project.property("VERSION_NAME")}"))
-    includes.from("README.md")
-}

dokka-hide-internal/build.gradle.kts

@@ -21,4 +21,7 @@ dependencies {
     testImplementation(libs.kotlin.test)
     testImplementation(libs.dokka.testApi)
     testImplementation(libs.dokka.baseTestUtils)
+    testRuntimeOnly(libs.dokka.analysisKotlinSymbols)
+    // Dokka 2.2 K2 analysis needs Kotlin stdlib APIs newer than the repo's 2.0.21 (test runtime only).
+    testRuntimeOnly("org.jetbrains.kotlin:kotlin-stdlib:${libs.versions.dokkaAnalysisKotlin.get()}")
 }

gradle/libs.versions.toml

@@ -31,7 +31,8 @@ datastorePreference = "1.0.0"
 dependencyGraph = "0.9"
 detekt = "1.23.8"
 detektRulesCompose = "0.4.10"
-dokka = "1.8.10"
+dokka = "2.2.0"
+dokkaAnalysisKotlin = "2.2.0"
 emergeGradlePlugin = "4.4.0"
 emergeSnapshots = "1.5.0"
 espresso = "3.6.1"
@@ -144,6 +145,7 @@ detekt-formatting = { module = "io.gitlab.arturbosch.detekt:detekt-formatting",
 detekt-libraries = { module = "io.gitlab.arturbosch.detekt:detekt-rules-libraries", version.ref = "detekt"}
 detekt-test = { module = "io.gitlab.arturbosch.detekt:detekt-test", version.ref = "detekt" }
 
+dokka-analysisKotlinSymbols = { module = "org.jetbrains.dokka:analysis-kotlin-symbols", version.ref = "dokka" }
 dokka-base = { module = "org.jetbrains.dokka:dokka-base", version.ref = "dokka" }
 dokka-baseTestUtils = { module = "org.jetbrains.dokka:dokka-base-test-utils", version.ref = "dokka" }
 dokka-core = { module = "org.jetbrains.dokka:dokka-core", version.ref = "dokka" }

purchases/build.gradle.kts

@@ -1,3 +1,4 @@
+import org.jetbrains.dokka.gradle.engine.parameters.DokkaSourceSetSpec
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
 import java.io.FileInputStream
 import java.util.Properties
@@ -237,44 +238,33 @@ dependencies {
     testImplementation(kotlin("test"))
 }
 
-tasks.dokkaHtmlPartial.configure {
+fun DokkaSourceSetSpec.configureDocumentedSourceSet() {
+    reportUndocumented.set(true)
+    skipDeprecated.set(true)
+    externalDocumentationLinks.register("android") {
+        url("https://developer.android.com/reference/")
+    }
+}
+
+dokka {
     dokkaSourceSets {
         named("customEntitlementComputation") {
             suppress.set(true)
         }
         named("defaults") {
-            dependsOn("main")
-            reportUndocumented.set(true)
-            includeNonPublic.set(false)
-            skipDeprecated.set(true)
-            externalDocumentationLink {
-                url.set(
-                    uri("https://developer.android.com/reference/package-list").toURL(),
-                )
-            }
+            dependentSourceSets.addLater(dokkaSourceSets.named("main").flatMap { it.sourceSetId })
+            configureDocumentedSourceSet()
+        }
+        named("main") {
+            configureDocumentedSourceSet()
             sourceLink {
-                localDirectory.set(
-                    file("src/main/kotlin"),
-                )
-                remoteUrl.set(
-                    uri("https://github.com/revenuecat/purchases-android/blob/main/purchases/src/main/kotlin").toURL(),
-                )
-                remoteLineSuffix.set("#L")
+                localDirectory.set(file("src/main/kotlin"))
+                remoteUrl("https://github.com/revenuecat/purchases-android/blob/main/purchases/src/main/kotlin")
             }
             sourceLink {
-                localDirectory.set(
-                    file("src/main/java"),
-                )
-                remoteUrl.set(
-                    uri("https://github.com/revenuecat/purchases-android/blob/main/public/src/main/java").toURL(),
-                )
-                remoteLineSuffix.set("#L")
+                localDirectory.set(file("src/main/java"))
+                remoteUrl("https://github.com/revenuecat/purchases-android/blob/main/purchases/src/main/java")
             }
-        }
-        named("main") {
-            reportUndocumented.set(true)
-            includeNonPublic.set(false)
-            skipDeprecated.set(true)
 
             // This package exclusively contains symbols annotated with @InternalRevenueCatAPI, for which no
             // documentation is generated due to our dokka-hide-internal plugin. However, by default Dokka still
@@ -283,29 +273,6 @@ tasks.dokkaHtmlPartial.configure {
                 matchingRegex.set("com\\.revenuecat\\.purchases\\.paywalls\\.components.*")
                 suppress.set(true)
             }
-            externalDocumentationLink {
-                url.set(
-                    uri("https://developer.android.com/reference/package-list").toURL(),
-                )
-            }
-            sourceLink {
-                localDirectory.set(
-                    file("src/main/kotlin"),
-                )
-                remoteUrl.set(
-                    uri(
-                        "https://github.com/revenuecat/purchases-android/blob/main/purchases/src/main/kotlin",
-                    ).toURL(),
-                )
-                remoteLineSuffix.set("#L")
-            }
-            sourceLink {
-                localDirectory.set(file("src/main/java"))
-                remoteUrl.set(
-                    uri("https://github.com/revenuecat/purchases-android/blob/main/public/src/main/java").toURL(),
-                )
-                remoteLineSuffix.set("#L")
-            }
         }
     }
 }

ui/revenuecatui/build.gradle.kts

@@ -135,31 +135,21 @@ dependencies {
     baselineProfile(project(":baselineprofile"))
 }
 
-tasks.dokkaHtmlPartial.configure {
+dokka {
     dokkaSourceSets {
         named("defaults") {
-            dependsOn("main")
+            dependentSourceSets.addLater(dokkaSourceSets.named("main").flatMap { it.sourceSetId })
         }
         named("main") {
             reportUndocumented.set(true)
-            includeNonPublic.set(false)
             skipDeprecated.set(true)
 
-            externalDocumentationLink {
-                url.set(
-                    uri("https://developer.android.com/reference/package-list").toURL(),
-                )
+            externalDocumentationLinks.register("android") {
+                url("https://developer.android.com/reference/")
             }
             sourceLink {
-                localDirectory.set(
-                    file("src/main/kotlin"),
-                )
-                remoteUrl.set(
-                    uri(
-                        "https://github.com/revenuecat/purchases-android/blob/main/ui/revenuecatui/src/main/kotlin",
-                    ).toURL(),
-                )
-                remoteLineSuffix.set("#L")
+                localDirectory.set(file("src/main/kotlin"))
+                remoteUrl("https://github.com/revenuecat/purchases-android/blob/main/ui/revenuecatui/src/main/kotlin")
             }
         }
     }