Merge branch 'master' into adam/feat/KT-70336/dgpv2-kdoc

docs/dokka.tree

@@ -6,7 +6,7 @@
 		<toc-element topic="dokka-get-started.md"/>
 		<toc-element toc-title="Run Dokka">
 			<toc-element topic="dokka-gradle.md"/>
-			<toc-element hidden="true" topic="dokka-migration.md"/>
+			<toc-element topic="dokka-migration.md"/>
 			<toc-element topic="dokka-maven.md"/>
 			<toc-element topic="dokka-cli.md"/>
 		</toc-element>

docs/topics/dokka-migration.md

@@ -51,7 +51,7 @@ Ensure that your project meets the minimum version requirements:
 
 2. In the project's `gradle.properties` file, set the following opt-in flag with helpers to activate the new plugin version:
 
-   ```kotlin
+   ```text
    org.jetbrains.dokka.experimental.gradle.pluginMode=V2EnabledWithHelpers
    ```
 
@@ -63,7 +63,6 @@ Ensure that your project meets the minimum version requirements:
    >
    {style="tip"}
 
-
 3. Sync your project with Gradle to ensure the new plugin is properly applied:
 
    * If you use IntelliJ IDEA, click the **Reload All Gradle Projects** ![Reload button](gradle-reload-button.png){width=30}{type="joined"} button from the Gradle tool window.
@@ -116,7 +115,7 @@ options according to your project setup:
           includes.from("README.md")
           sourceLink {
               localDirectory.set(file("src/main/kotlin"))
-              remoteUrl.set(URL("https://example.com/src"))
+              remoteUrl("https://example.com/src")
               remoteLineSuffix.set("#L")
           }
       }
@@ -148,6 +147,17 @@ options according to your project setup:
   documentedVisibilities.set(
       setOf(VisibilityModifier.Public)
   )
+  
+  // OR
+  
+  documentedVisibilities(VisibilityModifier.Public)
+  ```
+
+  Additionally, DGP v2 has a [utility function](https://github.com/Kotlin/dokka/blob/220922378e6c68eb148fda2ec80528a1b81478c9/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/HasConfigurableVisibilityModifiers.kt#L14-L16) for adding documented visibilities:
+ 
+  ```kotlin
+  fun documentedVisibilities(vararg visibilities: VisibilityModifier): Unit =
+      documentedVisibilities.set(visibilities.asList()) 
   ```
 
 * **External documentation link:** The source link configuration has [changed](https://docs.gradle.org/current/userguide/upgrading_version_8.html#deprecated_invalid_url_decoding). 
@@ -156,15 +166,33 @@ options according to your project setup:
   Previous configuration:
   
     ```kotlin
-    remoteUrl.set(URL("https://github.com/your-repo"))   
+    remoteUrl.set(URL("https://github.com/your-repo"))
     ```
   
   New configuration:
   
     ```kotlin
-    remoteUrl.set(URI("https://github.com/your-repo"))  
+    remoteUrl.set(URI("https://github.com/your-repo"))
+    
+    // OR
+    
+    remoteUrl("https://github.com/your-repo")
     ```
 
+  Additionally, DGP v2 has two [utility functions](https://github.com/Kotlin/dokka/blob/220922378e6c68eb148fda2ec80528a1b81478c9/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceLinkSpec.kt#L82-L96) 
+  for setting the URL:
+
+  ```kotlin
+  fun remoteUrl(@Language("http-url-reference") value: String): Unit =
+      remoteUrl.set(URI(value))
+  
+  // and
+  
+  fun remoteUrl(value: Provider<String>): Unit =
+      remoteUrl.set(value.map(::URI))
+  ```
+
+
 * **Custom assets:** The [`customAssets`](dokka-html.md#customize-assets) property now uses collections of files 
   ([`FileCollection`)](https://docs.gradle.org/8.10/userguide/lazy_configuration.html#working_with_files_in_lazy_properties) 
   instead of lists (`var List<File>`).
@@ -181,25 +209,23 @@ options according to your project setup:
     customAssets.from("example.png", "example2.png")
     ```
 
-* **Output directory:** Use the `dokka {}` block to specify a single output directory for all Dokka-generated documentation.
+* **Output directory:** Use the `dokka {}` block to specify the output directory for generated Dokka documentation.
 
     Previous configuration:
 
     ```kotlin
-    tasks.dokkaHtml{
-        dokkaSourceSets {
-            configureEach {
-                outputDirectory.set(layout.buildDirectory.dir("dokkaDir"))
-            }
-        }
+    tasks.dokkaHtml {
+        outputDirectory.set(layout.buildDirectory.dir("dokkaDir"))
     }
     ```
 
     New configuration:
 
     ```kotlin
     dokka {
-        dokkaPublicationDirectory.set(layout.buildDirectory.dir("dokkaDir"))
+        dokkaPublications.html {
+            outputDirectory.set(layout.buildDirectory.dir("dokkaDir"))
+        }
     }
     ```
 
@@ -266,7 +292,7 @@ After setting up the `buildSrc` directory:
     }
    
     dokka {
-    // The shared configuration goes here
+        // The shared configuration goes here
     }
     ```
 
@@ -325,7 +351,7 @@ DGP v2 has renamed the Gradle tasks that generate the API documentation.
 
 Previous task:
 
-```kotlin
+```text
 ./gradlew dokkaHtml
 
 // OR
@@ -335,7 +361,7 @@ Previous task:
 
 New task:
 
-```kotlin
+```text
 ./gradlew :dokkaGenerate
 ```
 
@@ -355,7 +381,7 @@ to generate output in HTML, Javadoc or both HTML and Javadoc. For more informati
 The default output format for DGP v2 is HTML. However, you can choose to generate the API documentation in HTML, Javadoc, 
 or both formats at the same time:
 
-1. Place the corresponding plugin `id` in the `plugins{}` block of your project's `build.gradle.kts` file:
+1. Place the corresponding plugin `id` in the `plugins {}` block of your project's `build.gradle.kts` file:
 
    ```kotlin
    plugins {
@@ -379,7 +405,7 @@ Here's a list of the plugin `id` and Gradle task that correspond to each format:
 | Gradle task | `./gradlew :dokkaGenerateHtml` | `./gradlew :dokkaGenerateJavadoc`   | `./gradlew :dokkaGenerate`        |
 
 > The `dokkaGenerate` task generates documentation in all available formats based on the applied plugins. 
-> If both the HTML and Javadoc plugins are applied, you can choose to generate only HTML format by running the `dokkaGenerateHtml` task, 
+> If both the HTML and Javadoc plugins are applied, you can choose to generate only HTML by running the `dokkaGenerateHtml` task, 
 > or only Javadoc by running the `dokkaGenerateJavadoc` task.
 > 
 {style="tip"}
@@ -398,7 +424,7 @@ After you've migrated your project, perform these steps to wrap up and improve p
 
 After successful migration, set the following opt-in flag without helpers in the project's `gradle.properties` file:
 
-```kotlin
+```text
 org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
 ```
 
@@ -416,4 +442,4 @@ DGP v2 now supports Gradle build cache and configuration cache, improving build
 
 * Explore more [DGP v2 project examples](https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2). 
 * [Get started with Dokka](dokka-get-started.md).
-* [Learn more about Dokka plugins](dokka-plugins.md).
+* [Learn more about Dokka plugins](dokka-plugins.md).

dokka-integration-tests/gradle/build.gradle.kts

@@ -93,6 +93,7 @@ registerTestProjectSuite("testTemplateProjectMultimodule1", "it-multimodule-1")
 registerTestProjectSuite("testTemplateProjectMultimoduleVersioning", "it-multimodule-versioning-0")
 registerTestProjectSuite("testTemplateProjectMultimoduleInterModuleLinks", "it-multimodule-inter-module-links")
 registerTestProjectSuite("testTemplateProjectMultiplatform", "it-multiplatform-0")
+registerTestProjectSuite("testTemplateProjectMultiplatformMultimodule", "it-multiplatform-multimodule")
 registerTestProjectSuite("testTemplateProjectTasksExecutionStress", "it-sequential-tasks-execution-stress")
 registerTestProjectSuite("testTemplateProjectWasmBasic", "it-wasm-basic")
 registerTestProjectSuite("testTemplateProjectWasmJsWasiBasic", "it-wasm-js-wasi-basic")

dokka-integration-tests/gradle/projects/it-multiplatform-multimodule/build.gradle.kts

@@ -0,0 +1,8 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+plugins {
+    kotlin("multiplatform") apply false
+    id("org.jetbrains.dokka")
+}

dokka-integration-tests/gradle/projects/it-multiplatform-multimodule/first/build.gradle.kts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+plugins {
+    kotlin("multiplatform")
+    id("org.jetbrains.dokka")
+}
+
+kotlin {
+    jvm()
+    linuxX64()
+    linuxArm64()
+    macosX64()
+    macosArm64()
+    js()
+}

dokka-integration-tests/gradle/projects/it-multiplatform-multimodule/first/src/commonMain/kotlin/Subclass.kt

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package it.mpp.first
+
+/**
+ * This is an annotation which should be used for opt-in
+ * e.g [SealedSerializationApi](https://github.com/Kotlin/kotlinx.serialization/blob/99be48514c1d0a975bb80d7bd37df429a9670064/core/commonMain/src/kotlinx/serialization/ApiLevels.kt#L50)
+ */
+@MustBeDocumented
+@RequiresOptIn
+annotation class SomeApi
+
+/**
+ * Class which should be somehow used by dependent module
+ */
+@OptIn(ExperimentalSubclassOptIn::class)
+@SubclassOptInRequired(SomeApi::class)
+interface Subclass

dokka-integration-tests/gradle/projects/it-multiplatform-multimodule/gradle.properties

@@ -0,0 +1,9 @@
+#
+# Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+#
+
+kotlin.js.compiler=ir
+
+# to sync the project locally, check dokka-integration-tests/gradle/projects/README.md
+#dokka_it_kotlin_version=
+#dokka_it_dokka_version=

dokka-integration-tests/gradle/projects/it-multiplatform-multimodule/second/build.gradle.kts

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+plugins {
+    kotlin("multiplatform")
+    id("org.jetbrains.dokka")
+}
+
+kotlin {
+    jvm()
+    linuxX64()
+    linuxArm64()
+    macosX64()
+    macosArm64()
+    js()
+
+    sourceSets {
+        commonMain {
+            dependencies {
+                api(project(":first"))
+            }
+        }
+    }
+}

dokka-integration-tests/gradle/projects/it-multiplatform-multimodule/second/src/commonMain/kotlin/Usage.kt

@@ -0,0 +1,10 @@
+package it.mpp.second
+
+import it.mpp.first.*
+
+/**
+ * exposes [Subclass] from another module which has [SubclassOptInRequired] annotation present
+ */
+class Usage(
+    val subclass: Subclass
+)

dokka-integration-tests/gradle/projects/it-multiplatform-multimodule/settings.gradle.kts

@@ -0,0 +1,9 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+apply(from = "template.settings.gradle.kts")
+rootProject.name = "it-multiplatform-multimodule"
+
+include(":first")
+include(":second")

dokka-integration-tests/gradle/projects/ui-showcase/build-logic/src/main/kotlin/uitest.dokka.gradle.kts

@@ -10,12 +10,9 @@ plugins {
 }
 
 tasks.withType<AbstractDokkaTask>().configureEach {
-    moduleVersion.set("1.0")
-
     @Language("JSON")
     val versioningPluginConfiguration = """
     {
-      "version": "1.0",
       "olderVersionsDir": "${project.rootProject.projectDir.resolve("previousDocVersions").invariantSeparatorsPath}"
     }
     """.trimIndent()

dokka-integration-tests/gradle/projects/ui-showcase/gradle.properties

@@ -2,6 +2,8 @@
 # Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
+version=2.0
+
 # to sync the project locally, check dokka-integration-tests/gradle/projects/README.md
 #dokka_it_kotlin_version=
 #dokka_it_dokka_version=