Merge remote-tracking branch 'origin/master' into project-structure-r…

…efactoring

# Conflicts:
#	dokka-runners/gradle-plugin-classic/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/KotlinNativeDistributionAccessor.kt

CONTRIBUTING.md

@@ -23,9 +23,9 @@ Bug reports, feature requests and questions are welcome. Submit issues [here](ht
 
 ## Submitting PRs
 
-Dokka has extensive [Developer Guides](https://kotlin.github.io/dokka/1.9.0/developer_guide/introduction/) documentation
-which goes over the development [Workflow](https://kotlin.github.io/dokka/1.9.0/developer_guide/workflow/) and 
-[Dokka's architecture](https://kotlin.github.io/dokka/1.9.0/developer_guide/architecture/architecture_overview/),
+Dokka has extensive [Developer Guides](https://kotlin.github.io/dokka/1.9.10/developer_guide/introduction/) documentation
+which goes over the development [Workflow](https://kotlin.github.io/dokka/1.9.10/developer_guide/workflow/) and 
+[Dokka's architecture](https://kotlin.github.io/dokka/1.9.10/developer_guide/architecture/architecture_overview/),
 which can help you understand how to achieve what you want and where to look.
 
 All development (both new features and bugfixes) takes place in the `master` branch, it contains sources for the next
@@ -61,18 +61,18 @@ Unit tests which are run as part of `build` should not take much time, but you c
 ### Use/test locally built Dokka
 
 Below you will find a bare-bones instruction on how to use and test locally built Dokka. For more details and examples, 
-visit [Workflow](https://kotlin.github.io/dokka/1.9.0/developer_guide/workflow/) topic.
+visit [Workflow](https://kotlin.github.io/dokka/1.9.10/developer_guide/workflow/) topic.
 
 1. Change `dokka_version` in `gradle.properties` to something that you will use later on as the dependency version.
-   For instance, you can set it to something like `1.9.0-my-fix-SNAPSHOT`.
+   For instance, you can set it to something like `1.9.10-my-fix-SNAPSHOT`.
 2. Publish it to Maven Local (`./gradlew publishToMavenLocal`)
 3. In the project for which you want to generate documentation add Maven Local as a buildscript/dependency
    repository (`mavenLocal()`)
 4. Update your Dokka dependency to the version you've just published:
 
 ```kotlin
 plugins {
-    id("org.jetbrains.dokka") version "1.9.0-my-fix-SNAPSHOT"
+    id("org.jetbrains.dokka") version "1.9.10-my-fix-SNAPSHOT"
 }
 ```
 

README.md

@@ -21,7 +21,7 @@ Some libraries that use Dokka for their API reference documentation:
 * [Bitmovin](https://cdn.bitmovin.com/player/android/3/docs/index.html)
 * [Hexagon](https://hexagonkt.com/api/index.html)
 * [Ktor](https://api.ktor.io/)
-* [OkHttp](https://square.github.io/okhttp/4.x/okhttp/okhttp3/) (Markdown)
+* [OkHttp](https://square.github.io/okhttp/5.x/okhttp/okhttp3/)
 * [Gradle](https://docs.gradle.org/current/kotlin-dsl/index.html)
 
 You can run Dokka using [Gradle](https://kotlinlang.org/docs/dokka-gradle.html), 
@@ -43,7 +43,7 @@ Apply the Gradle plugin for Dokka in the root build script of your project:
 
 ```kotlin
 plugins {
-    id("org.jetbrains.dokka") version "1.9.0"
+    id("org.jetbrains.dokka") version "1.9.10"
 }
 ```
 
@@ -65,7 +65,7 @@ Apply Gradle plugin for Dokka in the root project:
 
 ```groovy
 plugins {
-    id 'org.jetbrains.dokka' version '1.9.0'
+    id 'org.jetbrains.dokka' version '1.9.10'
 }
 ```
 
@@ -99,7 +99,7 @@ Add the Dokka Maven plugin to the `plugins` section of your POM file:
         <plugin>
             <groupId>org.jetbrains.dokka</groupId>
             <artifactId>dokka-maven-plugin</artifactId>
-            <version>1.9.0</version>
+            <version>1.9.10</version>
             <executions>
                 <execution>
                     <phase>pre-site</phase>
@@ -138,7 +138,7 @@ Android platform:
 
 ```kotlin
 dependencies {
-    dokkaPlugin("org.jetbrains.dokka:android-documentation-plugin:1.9.0")
+    dokkaPlugin("org.jetbrains.dokka:android-documentation-plugin:1.9.10")
 }
 ```
 
@@ -149,7 +149,7 @@ dependencies {
 
 ```groovy
 dependencies {
-    dokkaPlugin 'org.jetbrains.dokka:android-documentation-plugin:1.9.0'
+    dokkaPlugin 'org.jetbrains.dokka:android-documentation-plugin:1.9.10'
 }
 ```
 
@@ -168,7 +168,7 @@ dependencies {
             <plugin>
                 <groupId>org.jetbrains.dokka</groupId>
                 <artifactId>android-documentation-plugin</artifactId>
-                <version>1.9.0</version>
+                <version>1.9.10</version>
             </plugin>
         </dokkaPlugins>
     </configuration>
@@ -215,7 +215,7 @@ implement plugins for missing or very specific features that are not provided ou
 Learn more about Dokka plugins and their configuration in [Dokka plugins](https://kotlinlang.org/docs/dokka-plugins.html).
 
 If you want to learn how to develop Dokka plugins, see
-[Developer guides](https://kotlin.github.io/dokka/1.9.0/developer_guide/introduction/).
+[Developer guides](https://kotlin.github.io/dokka/1.9.10/developer_guide/introduction/).
 
 ## Community
 

build-logic/src/main/kotlin/org/jetbrains/conventions/maven-cli-setup.gradle.kts

@@ -22,7 +22,6 @@ plugins {
 abstract class MavenCliSetupExtension {
     abstract val mavenVersion: Property<String>
     abstract val mavenPluginToolsVersion: Property<String>
-    abstract val mavenBuildDir: DirectoryProperty
 
     /** Directory that will contain the unpacked Apache Maven dependency */
     abstract val mavenInstallDir: DirectoryProperty
@@ -43,7 +42,6 @@ val mavenCliSetupExtension =
         mavenVersion.convention(libs.versions.apacheMaven.core)
         mavenPluginToolsVersion.convention(libs.versions.apacheMaven.pluginTools)
 
-        mavenBuildDir.convention(layout.buildDirectory.dir("maven"))
         mavenInstallDir.convention(layout.buildDirectory.dir("apache-maven"))
 
         val isWindowsProvider =
@@ -81,7 +79,6 @@ val mavenBinary by configurations.registering {
 }
 
 tasks.clean {
-    delete(mavenCliSetupExtension.mavenBuildDir)
     delete(mavenCliSetupExtension.mavenInstallDir)
 }
 

docs-developer/src/doc/docs/developer_guide/workflow.md

@@ -42,7 +42,7 @@ Having built Dokka locally, you can publish it to `mavenLocal()`. This will allo
 project as well as debug code remotely.
 
 1. Change `dokka_version` in `gradle.properties` to something that you will use later on as the dependency version.
-   For instance, you can set it to something like `1.9.0-my-fix-SNAPSHOT`. This version will be propagated to plugins
+   For instance, you can set it to something like `1.9.10-my-fix-SNAPSHOT`. This version will be propagated to plugins
    that reside inside Dokka's project (such as `mathjax`, `kotlin-as-java`, etc).
 2. Publish it to Maven Local (`./gradlew publishToMavenLocal`). Corresponding artifacts should appear in `~/.m2`
 3. In the project you want to generate documentation for or debug on, add maven local as a plugin/dependency
@@ -55,7 +55,7 @@ repositories {
 4. Update your Dokka dependency to the version you've just published:
 ```kotlin
 plugins {
-    id("org.jetbrains.dokka") version "1.9.0-my-fix-SNAPSHOT"
+    id("org.jetbrains.dokka") version "1.9.10-my-fix-SNAPSHOT"
 }
 ```
 

docs/topics/dokka-introduction.md

@@ -15,7 +15,7 @@ Here are some libraries that use Dokka for their API reference documentation:
 * [Bitmovin](https://cdn.bitmovin.com/player/android/3/docs/index.html)
 * [Hexagon](https://hexagonkt.com/api/index.html)
 * [Ktor](https://api.ktor.io/)
-* [OkHttp](https://square.github.io/okhttp/4.x/okhttp/okhttp3/) (Markdown)
+* [OkHttp](https://square.github.io/okhttp/5.x/okhttp/okhttp3/)
 
 You can run Dokka using [Gradle](dokka-gradle.md), [Maven](dokka-maven.md) or from the [command line](dokka-cli.md). It is also
 [highly pluggable](dokka-plugins.md).

docs/topics/runners/dokka-maven.md

@@ -407,7 +407,7 @@ function in `kotlinx.coroutines`.
     <configuration>
         <sourceLinks>
             <link>
-                <path>${project.basedir}/src</path>
+                <path>src</path>
                 <url>https://github.com/kotlin/dokka/tree/master/src</url>
                 <lineSuffix>#L</lineSuffix>
             </link>
@@ -422,6 +422,9 @@ function in `kotlinx.coroutines`.
             The path to the local source directory. The path must be relative to the root of the
             current module.
         </p>
+        <p>
+            Note: Only Unix based paths are allowed, Windows-style paths will throw an error.
+        </p>
     </def>
     <def title="url">
         <p>

docs/v.list

@@ -4,9 +4,9 @@
 
 <vars>
     <var name="dokkaVersion"
-         value="1.9.0"
+         value="1.9.10"
          type="string"/>
     <var name="kotlinVersion"
-         value="1.9.0"
+         value="1.9.10"
          type="string"/>
 </vars>

dokka-integration-tests/gradle/projects/it-basic/build.gradle.kts

@@ -20,7 +20,7 @@ buildscript {
     }
 }
 
-version = "1.9.0-SNAPSHOT"
+version = "1.9.10-SNAPSHOT"
 
 apply(from = "../template.root.gradle.kts")
 

dokka-integration-tests/gradle/projects/it-configuration/build.gradle.kts

@@ -16,7 +16,7 @@ buildscript {
     }
 }
 
-version = "1.9.0-SNAPSHOT"
+version = "1.9.10-SNAPSHOT"
 
 apply(from = "../template.root.gradle.kts")
 

dokka-integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt

@@ -158,7 +158,7 @@ class BasicGradleIntegrationTest : AbstractGradleIntegrationTest() {
         val indexFile = File(this, "index.html")
         assertTrue(indexFile.isFile, "Missing index.html")
         assertTrue(
-            """<title>Basic Project 1.9.0-SNAPSHOT API </title>""" in indexFile.readText(),
+            """<title>Basic Project 1.9.10-SNAPSHOT API </title>""" in indexFile.readText(),
             "Header with version number not present in index.html"
         )
 

dokka-integration-tests/integration-test-utilities/src/main/kotlin/org/jetbrains/dokka/it/TestOutputCopier.kt

@@ -15,6 +15,6 @@ public interface TestOutputCopier {
         System.getenv("DOKKA_TEST_OUTPUT_PATH")?.also { location ->
             println("Copying to ${File(location).absolutePath}")
             projectOutputLocation.copyRecursively(File(location))
-        } ?: println("No path via env. varbiable 'DOKKA_TEST_OUTPUT_PATH' provided, skipping copying")
+        } ?: println("No path via env. variable 'DOKKA_TEST_OUTPUT_PATH' provided, skipping copying")
     }
 }

dokka-integration-tests/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt

@@ -4,9 +4,10 @@
 
 package org.jetbrains.dokka.it.maven
 
+import org.intellij.lang.annotations.Language
 import org.jetbrains.dokka.it.AbstractIntegrationTest
-import org.jetbrains.dokka.it.awaitProcessResult
 import org.jetbrains.dokka.it.ProcessResult
+import org.jetbrains.dokka.it.awaitProcessResult
 import java.io.File
 import kotlin.test.*
 
@@ -26,11 +27,33 @@ class MavenIntegrationTest : AbstractIntegrationTest() {
             writeText(readText().replace("\$dokka_version", currentDokkaVersion))
         }
         val customResourcesDir = File(templateProjectDir, "customResources")
-        if(customResourcesDir.exists() && customResourcesDir.isDirectory) {
+        if (customResourcesDir.exists() && customResourcesDir.isDirectory) {
             customResourcesDir.copyRecursively(File(projectDir, "customResources"), overwrite = true)
         }
     }
 
+    @Test
+    fun `dokka help`() {
+        val result = ProcessBuilder().directory(projectDir)
+            .command(mavenBinaryFile.absolutePath, "dokka:help", "-U", "-e")
+            .start()
+            .awaitProcessResult()
+
+        // format the output to remove blank lines and make newlines system-independent
+        val output = result.output.lines().filter { it.isNotBlank() }.joinToString("\n")
+
+        assertContains(
+            output,
+            """
+                |This plugin has 4 goals:
+                |dokka:dokka
+                |dokka:help
+                |dokka:javadoc
+                |dokka:javadocJar
+            """.trimMargin()
+        )
+    }
+
     @Test
     fun `dokka dokka`() {
         val result = ProcessBuilder().directory(projectDir)
@@ -67,7 +90,12 @@ class MavenIntegrationTest : AbstractIntegrationTest() {
         )
         assertTrue(stylesDir.resolve("custom-style-to-add.css").isFile)
         projectDir.allHtmlFiles().forEach { file ->
-            if(file.name != "navigation.html") assertTrue("custom-style-to-add.css" in file.readText(), "custom styles not added to html file ${file.name}")
+            if (file.name != "navigation.html") {
+                assertTrue(
+                    "custom-style-to-add.css" in file.readText(),
+                    "custom styles not added to html file ${file.name}"
+                )
+            }
         }
         assertTrue(stylesDir.resolve("custom-style-to-add.css").readText().contains("""/* custom stylesheet */"""))
         assertTrue(imagesDir.resolve("custom-resource.svg").isFile)
@@ -172,4 +200,20 @@ class MavenIntegrationTest : AbstractIntegrationTest() {
             )
         )
     }
+
+    companion object {
+        /*
+         * TODO replace with kotlin.test.assertContains after migrating to Kotlin language version 1.5+
+         */
+        fun assertContains(
+            charSequence: CharSequence,
+            @Language("TEXT") other: CharSequence,
+            ignoreCase: Boolean = false
+        ) {
+            asserter.assertTrue(
+                { "Expected the char sequence to contain the substring.\nCharSequence <$charSequence>, substring <$other>, ignoreCase <$ignoreCase>." },
+                charSequence.contains(other, ignoreCase)
+            )
+        }
+    }
 }

dokka-runners/gradle-plugin-classic/build.gradle.kts

@@ -14,10 +14,12 @@ dependencies {
     api("org.jetbrains.dokka:core")
 
     compileOnly(libs.gradlePlugin.kotlin)
+    compileOnly(libs.gradlePlugin.kotlin.klibCommonizerApi)
     compileOnly(libs.gradlePlugin.android)
 
     testImplementation(kotlin("test"))
     testImplementation(libs.gradlePlugin.kotlin)
+    testImplementation(libs.gradlePlugin.kotlin.klibCommonizerApi)
     testImplementation(libs.gradlePlugin.android)
 }
 

dokka-runners/gradle-plugin-classic/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/KotlinNativeDistributionAccessor.kt

@@ -0,0 +1,39 @@
+@file:Suppress("INVISIBLE_REFERENCE")
+package org.jetbrains.dokka.gradle.kotlin
+
+import java.io.File
+import org.gradle.api.Project
+import org.jetbrains.kotlin.commonizer.KonanDistribution
+import org.jetbrains.kotlin.commonizer.platformLibsDir
+import org.jetbrains.kotlin.commonizer.stdlib
+import org.jetbrains.kotlin.compilerRunner.konanHome
+import org.jetbrains.kotlin.konan.target.KonanTarget
+
+/**
+ * Provides access to the Kotlin/Native distribution components:
+ * * [stdlibDir] -- stdlib directory
+ * * [platformDependencies] -- list of directories to platform dependencies
+ *
+ * It uses Kotlin Gradle Plugin API that is guaranteed to be present in:
+ *  1.5 <= kotlinVersion <= 1.9
+ *
+ * It should not be used with Kotlin versions later than 1.9
+ */
+internal class KotlinNativeDistributionAccessor(
+  project: Project
+) {
+  private val konanDistribution = KonanDistribution(
+    @Suppress("INVISIBLE_MEMBER")
+    project.konanHome
+  )
+
+  val stdlibDir: File = konanDistribution.stdlib
+
+  fun platformDependencies(target: KonanTarget): List<File> = konanDistribution
+    .platformLibsDir
+    .resolve(target.name)
+    .listLibraryFiles()
+
+  private fun File.listLibraryFiles(): List<File> = listFiles().orEmpty()
+    .filter { it.isDirectory || it.extension == "klib" }
+}

dokka-runners/gradle-plugin-classic/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/kotlinClasspathUtils.kt

@@ -10,7 +10,6 @@ import org.jetbrains.dokka.gradle.isAndroidTarget
 import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet
 import org.jetbrains.kotlin.gradle.plugin.mpp.AbstractKotlinNativeCompilation
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
-import org.jetbrains.kotlin.gradle.tasks.KotlinCompileTool
 
 internal fun Project.classpathOf(sourceSet: KotlinSourceSet): FileCollection {
     val compilations = compilationsOf(sourceSet)
@@ -43,8 +42,24 @@ private fun KotlinCompilation.compileClasspathOf(project: Project): FileCollecti
 }
 
 private fun KotlinCompilation.newCompileClasspathOf(project: Project): FileCollection {
-    val compilationClasspath = (compileTaskProvider.get() as? KotlinCompileTool)?.libraries ?: project.files()
-    return compilationClasspath + platformDependencyFiles(project)
+    if (this.target.isAndroidTarget()) { // Workaround for https://youtrack.jetbrains.com/issue/KT-33893
+        return this.classpathOf(project)
+    }
+
+    val result = project.objects.fileCollection()
+    result.from({ compileDependencyFiles })
+
+    val kgpVersion = project.getKgpVersion()
+    // Since Kotlin 2.0 native distributiuon dependencies will be included to compileDependencyFiles
+    if (kgpVersion != null && kgpVersion <= KotlinGradlePluginVersion(1, 9, 255)) {
+        if (this is AbstractKotlinNativeCompilation) {
+            val kotlinNativeDistributionAccessor = KotlinNativeDistributionAccessor(project)
+            result.from(kotlinNativeDistributionAccessor.stdlibDir)
+            result.from(kotlinNativeDistributionAccessor.platformDependencies(konanTarget))
+        }
+    }
+
+    return result
 }
 
 private fun KotlinCompilation.oldCompileClasspathOf(project: Project): FileCollection {