diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f5b60bc1de..1dba67f59e 100644 --- a/CONTRIBUTING.md +++ b/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,10 +61,10 @@ 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()`) @@ -72,7 +72,7 @@ visit [Workflow](https://kotlin.github.io/dokka/1.9.0/developer_guide/workflow/) ```kotlin plugins { - id("org.jetbrains.dokka") version "1.9.0-my-fix-SNAPSHOT" + id("org.jetbrains.dokka") version "1.9.10-my-fix-SNAPSHOT" } ``` diff --git a/README.md b/README.md index ff16e45d52..ed09a9502c 100644 --- a/README.md +++ b/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: org.jetbrains.dokka dokka-maven-plugin - 1.9.0 + 1.9.10 pre-site @@ -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 { org.jetbrains.dokka android-documentation-plugin - 1.9.0 + 1.9.10 @@ -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 diff --git a/build-logic/src/main/kotlin/org/jetbrains/conventions/maven-cli-setup.gradle.kts b/build-logic/src/main/kotlin/org/jetbrains/conventions/maven-cli-setup.gradle.kts index 8d228bc355..f07ff98d6b 100644 --- a/build-logic/src/main/kotlin/org/jetbrains/conventions/maven-cli-setup.gradle.kts +++ b/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 abstract val mavenPluginToolsVersion: Property - 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) } diff --git a/docs-developer/src/doc/docs/developer_guide/workflow.md b/docs-developer/src/doc/docs/developer_guide/workflow.md index 26452281bb..4b08d44fae 100644 --- a/docs-developer/src/doc/docs/developer_guide/workflow.md +++ b/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" } ``` diff --git a/docs/topics/dokka-introduction.md b/docs/topics/dokka-introduction.md index fd33a3cbff..e4bff95ad3 100644 --- a/docs/topics/dokka-introduction.md +++ b/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). diff --git a/docs/topics/runners/dokka-maven.md b/docs/topics/runners/dokka-maven.md index 14551c91d3..bc51d5fee1 100644 --- a/docs/topics/runners/dokka-maven.md +++ b/docs/topics/runners/dokka-maven.md @@ -407,7 +407,7 @@ function in `kotlinx.coroutines`. - ${project.basedir}/src + src https://github.com/kotlin/dokka/tree/master/src #L @@ -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.

+

+ Note: Only Unix based paths are allowed, Windows-style paths will throw an error. +

diff --git a/docs/v.list b/docs/v.list index c17d5c7fbf..34141810d4 100644 --- a/docs/v.list +++ b/docs/v.list @@ -4,9 +4,9 @@ diff --git a/dokka-integration-tests/gradle/projects/it-basic/build.gradle.kts b/dokka-integration-tests/gradle/projects/it-basic/build.gradle.kts index 4ec3b82500..5cb354f4a0 100644 --- a/dokka-integration-tests/gradle/projects/it-basic/build.gradle.kts +++ b/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") diff --git a/dokka-integration-tests/gradle/projects/it-configuration/build.gradle.kts b/dokka-integration-tests/gradle/projects/it-configuration/build.gradle.kts index 02e99e9b44..76e3f6512a 100644 --- a/dokka-integration-tests/gradle/projects/it-configuration/build.gradle.kts +++ b/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") diff --git a/dokka-integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt b/dokka-integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt index f214710caf..a23fb41037 100644 --- a/dokka-integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt +++ b/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( - """Basic Project 1.9.0-SNAPSHOT API """ in indexFile.readText(), + """Basic Project 1.9.10-SNAPSHOT API """ in indexFile.readText(), "Header with version number not present in index.html" ) diff --git a/dokka-integration-tests/integration-test-utilities/src/main/kotlin/org/jetbrains/dokka/it/TestOutputCopier.kt b/dokka-integration-tests/integration-test-utilities/src/main/kotlin/org/jetbrains/dokka/it/TestOutputCopier.kt index 681c9d539f..2e2113a910 100644 --- a/dokka-integration-tests/integration-test-utilities/src/main/kotlin/org/jetbrains/dokka/it/TestOutputCopier.kt +++ b/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") } } diff --git a/dokka-integration-tests/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt b/dokka-integration-tests/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt index 92bdc45ecd..7606072c80 100644 --- a/dokka-integration-tests/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt +++ b/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) + ) + } + } } diff --git a/dokka-runners/gradle-plugin-classic/build.gradle.kts b/dokka-runners/gradle-plugin-classic/build.gradle.kts index 43e45ade27..fd3197adb5 100644 --- a/dokka-runners/gradle-plugin-classic/build.gradle.kts +++ b/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) } diff --git a/dokka-runners/gradle-plugin-classic/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/KotlinNativeDistributionAccessor.kt b/dokka-runners/gradle-plugin-classic/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/KotlinNativeDistributionAccessor.kt new file mode 100644 index 0000000000..3180efef47 --- /dev/null +++ b/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 = konanDistribution + .platformLibsDir + .resolve(target.name) + .listLibraryFiles() + + private fun File.listLibraryFiles(): List = listFiles().orEmpty() + .filter { it.isDirectory || it.extension == "klib" } +} \ No newline at end of file diff --git a/dokka-runners/gradle-plugin-classic/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/kotlinClasspathUtils.kt b/dokka-runners/gradle-plugin-classic/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/kotlinClasspathUtils.kt index 4fdc61c9f6..778261a7a3 100644 --- a/dokka-runners/gradle-plugin-classic/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/kotlinClasspathUtils.kt +++ b/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 { diff --git a/dokka-runners/maven-plugin/api/maven-plugin.api b/dokka-runners/maven-plugin/api/maven-plugin.api index 28d96bd3b6..069e7744ee 100644 --- a/dokka-runners/maven-plugin/api/maven-plugin.api +++ b/dokka-runners/maven-plugin/api/maven-plugin.api @@ -94,6 +94,11 @@ public final class org/jetbrains/dokka/maven/ExternalDocumentationLinkBuilder { public final fun setUrl (Ljava/net/URL;)V } +public class org/jetbrains/dokka/maven/HelpMojo : org/apache/maven/plugin/AbstractMojo { + public fun ()V + public fun execute ()V +} + public final class org/jetbrains/dokka/maven/MavenDokkaLogger : org/jetbrains/dokka/utilities/DokkaLogger { public fun (Lorg/apache/maven/plugin/logging/Log;)V public fun debug (Ljava/lang/String;)V diff --git a/dokka-runners/maven-plugin/build.gradle.kts b/dokka-runners/maven-plugin/build.gradle.kts index 5e27929835..825493ad27 100644 --- a/dokka-runners/maven-plugin/build.gradle.kts +++ b/dokka-runners/maven-plugin/build.gradle.kts @@ -2,7 +2,6 @@ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. */ -import org.gradle.kotlin.dsl.support.appendReproducibleNewLine import org.jetbrains.registerDokkaArtifactPublication plugins { @@ -47,77 +46,93 @@ val generatePom by tasks.registering(Sync::class) { into(temporaryDir) } -val prepareMavenPluginBuildDir by tasks.registering(Sync::class) { - description = "Prepares all files for Maven Plugin task execution" +val prepareHelpMojoDir by tasks.registering(Sync::class) { + description = "Prepare files for generating the Maven Plugin HelpMojo" group = mavenPluginTaskGroup - from(tasks.compileKotlin.flatMap { it.destinationDirectory }) { into("classes/java/main") } - from(tasks.compileJava.flatMap { it.destinationDirectory }) { into("classes/java/main") } - + into(layout.buildDirectory.dir("maven-help-mojo")) from(generatePom) - - into(mavenCliSetup.mavenBuildDir) } val helpMojo by tasks.registering(Exec::class) { + description = "Generate the Maven Plugin HelpMojo" group = mavenPluginTaskGroup - dependsOn(tasks.installMavenBinary, prepareMavenPluginBuildDir) + dependsOn(tasks.installMavenBinary, prepareHelpMojoDir) - workingDir(mavenCliSetup.mavenBuildDir) + workingDir(prepareHelpMojoDir.map { it.destinationDir }) executable(mavenCliSetup.mvn.get()) args("-e", "-B", "org.apache.maven.plugins:maven-plugin-plugin:helpmojo") - outputs.dir(mavenCliSetup.mavenBuildDir) - - doLast("normalize maven-plugin-help.properties") { - // The maven-plugin-help.properties file contains a timestamp by default. - // It should be removed as it is not reproducible and impacts Gradle caching - val pluginHelpProperties = workingDir.resolve("maven-plugin-help.properties") - pluginHelpProperties.writeText( - buildString { - val lines = pluginHelpProperties.readText().lines().iterator() - // the first line is a descriptive comment - appendReproducibleNewLine(lines.next()) - // the second line is the timestamp, which should be ignored - lines.next() - // the remaining lines are properties - lines.forEach { appendReproducibleNewLine(it) } - } - ) + outputs.dir(workingDir) +} + +val helpMojoSources by tasks.registering(Sync::class) { + description = "Sync the HelpMojo source files into a SourceSet SrcDir" + group = mavenPluginTaskGroup + from(helpMojo) { + eachFile { + // drop 2 leading directories + relativePath = RelativePath(true, *relativePath.segments.drop(2).toTypedArray()) + } } + includeEmptyDirs = false + into(temporaryDir) + include("**/*.java") +} + +val helpMojoResources by tasks.registering(Sync::class) { + description = "Sync the HelpMojo resource files into a SourceSet SrcDir" + group = mavenPluginTaskGroup + from(helpMojo) + into(temporaryDir) + include("**/**") + exclude("**/*.java") +} + +sourceSets.main { + // use the generated HelpMojo as compilation input, so Gradle will automatically generate the mojo + java.srcDirs(helpMojoSources) + resources.srcDirs(helpMojoResources) +} + +val preparePluginDescriptorDir by tasks.registering(Sync::class) { + description = "Prepare files for generating the Maven Plugin descriptor" + group = mavenPluginTaskGroup + + into(layout.buildDirectory.dir("maven-plugin-descriptor")) + + from(tasks.compileKotlin) { into("classes/java/main") } + from(tasks.compileJava) { into("classes/java/main") } + from(helpMojoResources) } val pluginDescriptor by tasks.registering(Exec::class) { + description = "Generate the Maven Plugin descriptor" group = mavenPluginTaskGroup - dependsOn(tasks.installMavenBinary, prepareMavenPluginBuildDir) + dependsOn(tasks.installMavenBinary, preparePluginDescriptorDir) - workingDir(mavenCliSetup.mavenBuildDir) + workingDir(preparePluginDescriptorDir.map { it.destinationDir }) executable(mavenCliSetup.mvn.get()) - args( - "-e", - "-B", - "org.apache.maven.plugins:maven-plugin-plugin:descriptor" - ) + args("-e", "-B", "org.apache.maven.plugins:maven-plugin-plugin:descriptor") - outputs.dir(layout.buildDirectory.dir("maven/classes/java/main/META-INF/maven")) + outputs.dir("$workingDir/classes/java/main/META-INF/maven") } tasks.jar { - dependsOn(pluginDescriptor, helpMojo) metaInf { - from(mavenCliSetup.mavenBuildDir.map { it.dir("classes/java/main/META-INF") }) + from(pluginDescriptor) { + into("maven") + } } manifest { attributes("Class-Path" to configurations.runtimeClasspath.map { configuration -> configuration.resolve().joinToString(" ") { it.name } }) } - duplicatesStrategy = DuplicatesStrategy.WARN } - registerDokkaArtifactPublication("dokkaMavenPlugin") { artifactId = "dokka-maven-plugin" } diff --git a/dokka-runners/maven-plugin/pom.template.xml b/dokka-runners/maven-plugin/pom.template.xml index 01ad60d268..b47951125d 100644 --- a/dokka-runners/maven-plugin/pom.template.xml +++ b/dokka-runners/maven-plugin/pom.template.xml @@ -12,6 +12,7 @@ maven-plugin ${mavenVersion} + UTF-8 @@ -21,10 +22,35 @@ ${mavenPluginToolsVersion} org.jetbrains.dokka.maven + true + + + default-descriptor + + descriptor + + process-classes + + + help-descriptor + + helpmojo + + process-classes + + ./ ./classes/java/main + + + org.apache.maven.plugin-tools + maven-plugin-annotations + ${mavenPluginToolsVersion} + provided + + diff --git a/dokka-runners/maven-plugin/src/main/kotlin/DokkaMojo.kt b/dokka-runners/maven-plugin/src/main/kotlin/DokkaMojo.kt index ba95e7a70c..d14fea9c5b 100644 --- a/dokka-runners/maven-plugin/src/main/kotlin/DokkaMojo.kt +++ b/dokka-runners/maven-plugin/src/main/kotlin/DokkaMojo.kt @@ -389,7 +389,7 @@ public abstract class AbstractDokkaMojo( skipEmptyPackages = skipEmptyPackages, skipDeprecated = skipDeprecated, jdkVersion = jdkVersion, - sourceLinks = sourceLinks.map { SourceLinkDefinitionImpl(it.path, URL(it.url), it.lineSuffix) }.toSet(), + sourceLinks = sourceLinks.map { SourceLinkDefinitionImpl(File(it.path).canonicalPath, URL(it.url), it.lineSuffix) }.toSet(), perPackageOptions = perPackageOptions.map { @Suppress("DEPRECATION") // for includeNonPublic, preserve backwards compatibility PackageOptionsImpl( diff --git a/dokka-subprojects/analysis-kotlin-symbols/build.gradle.kts b/dokka-subprojects/analysis-kotlin-symbols/build.gradle.kts index 2500050a38..5dc1d72e9d 100644 --- a/dokka-subprojects/analysis-kotlin-symbols/build.gradle.kts +++ b/dokka-subprojects/analysis-kotlin-symbols/build.gradle.kts @@ -54,7 +54,6 @@ dependencies { listOf( libs.kotlin.high.level.api.api, libs.kotlin.analysis.api.standalone, - libs.kotlin.high.level.api.impl // for Standalone prototype ).forEach { implementation(it) { isTransitive = false // see KTIJ-19820 @@ -67,7 +66,7 @@ dependencies { libs.kotlin.low.level.api.fir, libs.kotlin.analysis.project.structure, libs.kotlin.analysis.api.providers, - libs.kotlin.symbol.light.classes + libs.kotlin.symbol.light.classes, ).forEach { runtimeOnly(it) { isTransitive = false // see KTIJ-19820 diff --git a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/AnalysisContext.kt b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/AnalysisContext.kt index 9ccd52b297..cf57e81539 100644 --- a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/AnalysisContext.kt +++ b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/AnalysisContext.kt @@ -125,11 +125,12 @@ internal open class EnvironmentKotlinAnalysis( internal interface AnalysisContext: Closeable { val project: Project val mainModule: KtSourceModule + val analysisSession: StandaloneAnalysisAPISession } private class AnalysisContextImpl( override val mainModule: KtSourceModule, - private val analysisSession: StandaloneAnalysisAPISession, + override val analysisSession: StandaloneAnalysisAPISession, private val applicationDisposable: Disposable, private val projectDisposable: Disposable ) : AnalysisContext { diff --git a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/KotlinAnalysis.kt b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/KotlinAnalysis.kt index 9419ec651c..a6155fb028 100644 --- a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/KotlinAnalysis.kt +++ b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/KotlinAnalysis.kt @@ -4,19 +4,11 @@ package org.jetbrains.dokka.analysis.kotlin.symbols.plugin -import com.intellij.core.CoreApplicationEnvironment import com.intellij.openapi.Disposable -import com.intellij.openapi.project.Project -import com.intellij.openapi.vfs.StandardFileSystems -import com.intellij.openapi.vfs.VirtualFileManager -import com.intellij.psi.PsiFileSystemItem -import com.intellij.psi.PsiManager -import com.intellij.psi.search.GlobalSearchScope -import com.intellij.psi.search.ProjectScope -import com.intellij.util.io.URLUtil import org.jetbrains.dokka.Platform -import org.jetbrains.kotlin.analysis.api.impl.base.util.LibraryUtils -import org.jetbrains.kotlin.analysis.api.resolve.extensions.KtResolveExtensionProvider +import org.jetbrains.kotlin.analysis.api.KtAnalysisApiInternals +import org.jetbrains.kotlin.analysis.api.lifetime.KtLifetimeTokenProvider +import org.jetbrains.kotlin.analysis.api.standalone.KtAlwaysAccessibleLifetimeTokenProvider import org.jetbrains.kotlin.analysis.api.standalone.StandaloneAnalysisAPISession import org.jetbrains.kotlin.analysis.api.standalone.buildStandaloneAnalysisAPISession import org.jetbrains.kotlin.analysis.project.structure.KtSourceModule @@ -24,18 +16,12 @@ import org.jetbrains.kotlin.analysis.project.structure.builder.KtModuleBuilder import org.jetbrains.kotlin.analysis.project.structure.builder.buildKtLibraryModule import org.jetbrains.kotlin.analysis.project.structure.builder.buildKtSdkModule import org.jetbrains.kotlin.analysis.project.structure.builder.buildKtSourceModule -import org.jetbrains.kotlin.cli.jvm.compiler.TopDownAnalyzerFacadeForJVM import org.jetbrains.kotlin.config.* -import org.jetbrains.kotlin.idea.KotlinFileType import org.jetbrains.kotlin.platform.CommonPlatforms import org.jetbrains.kotlin.platform.js.JsPlatforms import org.jetbrains.kotlin.platform.jvm.JvmPlatforms import org.jetbrains.kotlin.platform.konan.NativePlatforms -import org.jetbrains.kotlin.psi.KtFile import java.io.File -import java.io.IOException -import java.nio.file.* -import java.nio.file.attribute.BasicFileAttributes internal fun Platform.toTargetPlatform() = when (this) { Platform.js, Platform.wasm -> JsPlatforms.defaultJsPlatform @@ -71,6 +57,7 @@ internal fun getLanguageVersionSettings( } // it should be changed after https://github.com/Kotlin/dokka/issues/3114 +@OptIn(KtAnalysisApiInternals::class) internal fun createAnalysisSession( classpath: List, sourceRoots: Set, @@ -87,163 +74,40 @@ internal fun createAnalysisSession( projectDisposable = projectDisposable, withPsiDeclarationFromBinaryModuleProvider = false ) { - val project = project + registerProjectService(KtLifetimeTokenProvider::class.java, KtAlwaysAccessibleLifetimeTokenProvider()) val targetPlatform = analysisPlatform.toTargetPlatform() - fun KtModuleBuilder.addModuleDependencies(moduleName: String) { + + buildKtModuleProvider { val libraryRoots = classpath - addRegularDependency( - buildKtLibraryModule { - contentScope = ProjectScope.getLibrariesScope(project) - this.platform = targetPlatform - this.project = project - binaryRoots = libraryRoots.map { it.toPath() } - libraryName = "Library for $moduleName" - } - ) - getJdkHomeFromSystemProperty()?.let { jdkHome -> - val vfm = VirtualFileManager.getInstance() - val jdkHomePath = jdkHome.toPath() - val jdkHomeVirtualFile = vfm.findFileByNioPath(jdkHome.toPath())//vfm.findFileByPath(jdkHomePath) - val binaryRoots = LibraryUtils.findClassesFromJdkHome(jdkHomePath).map { - Paths.get(URLUtil.extractPath(it)) - } + fun KtModuleBuilder.addModuleDependencies(moduleName: String) { addRegularDependency( - buildKtSdkModule { - contentScope = GlobalSearchScope.fileScope(project, jdkHomeVirtualFile) + buildKtLibraryModule { this.platform = targetPlatform - this.project = project - this.binaryRoots = binaryRoots - sdkName = "JDK for $moduleName" + addBinaryRoots(libraryRoots.map { it.toPath() }) + libraryName = "Library for $moduleName" } ) + getJdkHomeFromSystemProperty()?.let { jdkHome -> + addRegularDependency( + buildKtSdkModule { + this.platform = targetPlatform + addBinaryRootsFromJdkHome(jdkHome.toPath(), isJre = true) + sdkName = "JDK for $moduleName" + } + ) + } + } + sourceModule = buildKtSourceModule { + languageVersionSettings = getLanguageVersionSettings(languageVersion, apiVersion) + platform = targetPlatform + moduleName = "" + // TODO: We should handle (virtual) file changes announced via LSP with the VFS + addSourceRoots(sourceRoots.map { it.toPath() }) + addModuleDependencies(moduleName) } - } - sourceModule = buildKtSourceModule { - this.languageVersionSettings = getLanguageVersionSettings(languageVersion, apiVersion) - - //val fs = StandardFileSystems.local() - //val psiManager = PsiManager.getInstance(project) - // TODO: We should handle (virtual) file changes announced via LSP with the VFS - /*val ktFiles = sources - .flatMap { Files.walk(it).toList() } - .mapNotNull { fs.findFileByPath(it.toString()) } - .mapNotNull { psiManager.findFile(it) } - .map { it as KtFile }*/ - val sourcePaths = sourceRoots.map { it.absolutePath } - val (ktFilePath, javaFilePath) = getSourceFilePaths(sourcePaths).partition { it.endsWith(KotlinFileType.EXTENSION) } - val javaFiles: List = getPsiFilesFromPaths(project, javaFilePath) - val ktFiles: List = getPsiFilesFromPaths(project, getSourceFilePaths(ktFilePath)) - addSourceRoots(ktFiles + javaFiles) - contentScope = TopDownAnalyzerFacadeForJVM.newModuleSearchScope(project, ktFiles) - platform = targetPlatform - moduleName = "" - this.project = project - addModuleDependencies(moduleName) - } - - buildKtModuleProvider { platform = targetPlatform - this.project = project addModule(sourceModule!!) } } - // TODO remove further - CoreApplicationEnvironment.registerExtensionPoint( - analysisSession.project.extensionArea, - KtResolveExtensionProvider.EP_NAME.name, - KtResolveExtensionProvider::class.java - ) return Pair(analysisSession, sourceModule ?: throw IllegalStateException()) -} - -// ----------- copy-paste from Analysis API ---------------------------------------------------------------------------- -/** - * Collect source file path from the given [root] store them in [result]. - * - * E.g., for `project/app/src` as a [root], this will walk the file tree and - * collect all `.kt` and `.java` files under that folder. - * - * Note that this util gracefully skips [IOException] during file tree traversal. - */ -internal fun collectSourceFilePaths( - root: Path, - result: MutableSet -) { - // NB: [Files#walk] throws an exception if there is an issue during IO. - // With [Files#walkFileTree] with a custom visitor, we can take control of exception handling. - Files.walkFileTree( - root, - object : SimpleFileVisitor() { - override fun preVisitDirectory(dir: Path, attrs: BasicFileAttributes): FileVisitResult { - return if (Files.isReadable(dir)) - FileVisitResult.CONTINUE - else - FileVisitResult.SKIP_SUBTREE - } - - override fun visitFile(file: Path, attrs: BasicFileAttributes): FileVisitResult { - if (!Files.isRegularFile(file) || !Files.isReadable(file)) - return FileVisitResult.CONTINUE - val ext = file.toFile().extension - if (ext == KotlinFileType.EXTENSION || ext == "java"/*JavaFileType.DEFAULT_EXTENSION*/) { - result.add(file.toString()) - } - return FileVisitResult.CONTINUE - } - - override fun visitFileFailed(file: Path, exc: IOException?): FileVisitResult { - // TODO: report or log [IOException]? - // NB: this intentionally swallows the exception, hence fail-safe. - // Skipping subtree doesn't make any sense, since this is not a directory. - // Skipping sibling may drop valid file paths afterward, so we just continue. - return FileVisitResult.CONTINUE - } - } - ) -} - -/** - * Collect source file path as [String] from the given source roots in [sourceRoot]. - * - * this util collects all `.kt` and `.java` files under source roots. - */ -internal fun getSourceFilePaths( - sourceRoot: Collection, - includeDirectoryRoot: Boolean = false, -): Set { - val result = mutableSetOf() - sourceRoot.forEach { srcRoot -> - val path = Paths.get(srcRoot) - if (Files.isDirectory(path)) { - // E.g., project/app/src - collectSourceFilePaths(path, result) - if (includeDirectoryRoot) { - result.add(srcRoot) - } - } else { - // E.g., project/app/src/some/pkg/main.kt - result.add(srcRoot) - } - } - - return result -} - -internal inline fun getPsiFilesFromPaths( - project: Project, - paths: Collection, -): List { - val fs = StandardFileSystems.local() - val psiManager = PsiManager.getInstance(project) - val result = mutableListOf() - for (path in paths) { - val vFile = fs.findFileByPath(path) ?: continue - val psiFileSystemItem = - if (vFile.isDirectory) - psiManager.findDirectory(vFile) as? T - else - psiManager.findFile(vFile) as? T - psiFileSystemItem?.let { result.add(it) } - } - return result -} +} \ No newline at end of file diff --git a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/SymbolsAnalysisPlugin.kt b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/SymbolsAnalysisPlugin.kt index 43435a55ca..ef79514567 100644 --- a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/SymbolsAnalysisPlugin.kt +++ b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/SymbolsAnalysisPlugin.kt @@ -93,7 +93,7 @@ public class SymbolsAnalysisPlugin : DokkaPlugin() { plugin().documentableSourceLanguageParser providing { KotlinDocumentableSourceLanguageParser() } } internal val symbolFullClassHierarchyBuilder by extending { - plugin().fullClassHierarchyBuilder providing { SymbolFullClassHierarchyBuilder() } + plugin().fullClassHierarchyBuilder providing ::SymbolFullClassHierarchyBuilder } internal val symbolSyntheticDocumentableDetector by extending { diff --git a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/services/SymbolFullClassHierarchyBuilder.kt b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/services/SymbolFullClassHierarchyBuilder.kt index 375aee9065..0e90bec8e8 100644 --- a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/services/SymbolFullClassHierarchyBuilder.kt +++ b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/services/SymbolFullClassHierarchyBuilder.kt @@ -16,12 +16,18 @@ import org.jetbrains.kotlin.analysis.api.types.KtType import org.jetbrains.dokka.analysis.kotlin.internal.ClassHierarchy import org.jetbrains.dokka.analysis.kotlin.internal.FullClassHierarchyBuilder import org.jetbrains.dokka.analysis.kotlin.internal.Supertypes +import org.jetbrains.dokka.analysis.kotlin.symbols.plugin.SymbolsAnalysisPlugin +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.plugability.plugin +import org.jetbrains.dokka.plugability.querySingle import org.jetbrains.kotlin.psi.KtClassOrObject import java.util.concurrent.ConcurrentHashMap -internal class SymbolFullClassHierarchyBuilder : FullClassHierarchyBuilder { - override suspend fun build(module: DModule): ClassHierarchy { +internal class SymbolFullClassHierarchyBuilder(val context: DokkaContext) : FullClassHierarchyBuilder { + private val kotlinAnalysis = context.plugin().querySingle { kotlinAnalysis } + + override suspend fun build(module: DModule): ClassHierarchy { val map = module.sourceSets.associateWith { ConcurrentHashMap>() } module.packages.forEach { visitDocumentable(it, map) } return map @@ -41,7 +47,7 @@ internal class SymbolFullClassHierarchyBuilder : FullClassHierarchyBuilder { if (supersMap[dri] == null) { supersMap[dri] = supertypesDriWithKType.map { it.first } - supertypesDriWithKType.forEach{ collectSupertypesFromKtType(it, supersMap) } + supertypesDriWithKType.forEach { collectSupertypesFromKtType(it, supersMap) } } } @@ -73,7 +79,7 @@ internal class SymbolFullClassHierarchyBuilder : FullClassHierarchyBuilder { documentable.sources.forEach { (sourceSet, source) -> if (source is KtPsiDocumentableSource) { (source.psi as? KtClassOrObject)?.let { psi -> - analyze(psi) { + analyze(kotlinAnalysis[sourceSet].mainModule) { val type = psi.getNamedClassOrObjectSymbol()?.buildSelfClassType() ?: return@analyze hierarchy[sourceSet]?.let { collectSupertypesFromKtType(documentable.dri to type, it) } } diff --git a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/DefaultSymbolToDocumentableTranslator.kt b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/DefaultSymbolToDocumentableTranslator.kt index 4e741d09e1..74d312690f 100644 --- a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/DefaultSymbolToDocumentableTranslator.kt +++ b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/DefaultSymbolToDocumentableTranslator.kt @@ -118,10 +118,7 @@ internal class DokkaSymbolVisitor( } fun visitModule(): DModule { - val ktFiles: List = getPsiFilesFromPaths( - analysisContext.project, - getSourceFilePaths(sourceSet.sourceRoots.map { it.canonicalPath }) - ) + val ktFiles = analysisContext.analysisSession.modulesWithFiles.entries.single().value.filterIsInstance() val processedPackages: MutableSet = mutableSetOf() return analyze(analysisContext.mainModule) { val packageSymbols: List = ktFiles @@ -343,7 +340,30 @@ internal class DokkaSymbolVisitor( KtClassKind.ANONYMOUS_OBJECT -> throw NotImplementedError("ANONYMOUS_OBJECT does not support") KtClassKind.ENUM_CLASS -> { - val entries = namedClassOrObjectSymbol.getEnumEntries().map { visitEnumEntrySymbol(it) } + /** + * See https://github.com/Kotlin/dokka/issues/3129 + * + * e.g. the `A` enum entry in the `enum E` is + * ``` + * static val A: E = object : E() { + * val x: Int = 5 + * } + * ``` + * it needs to exclude all static members like `values` and `valueOf` from the enum class's scope + */ + val enumEntryScope = lazy { + getDokkaScopeFrom(namedClassOrObjectSymbol, dri, includeStaticScope = false).let { + it.copy( + functions = it.functions.map { it.withNewExtras( it.extra + InheritedMember(dri.copy(callable = null).toSourceSetDependent())) }, + properties = it.properties.map { it.withNewExtras( it.extra + InheritedMember(dri.copy(callable = null).toSourceSetDependent())) } + ) + } + } + + val entries = + namedClassOrObjectSymbol.getEnumEntries().map { + visitEnumEntrySymbol(it, enumEntryScope.value) + } DEnum( dri = dri, @@ -383,12 +403,17 @@ internal class DokkaSymbolVisitor( val properties: List, val classlikes: List ) + + /** + * @param includeStaticScope flag to add static members, e.g. `valueOf`, `values` and `entries` members for Enum + */ private fun KtAnalysisSession.getDokkaScopeFrom( namedClassOrObjectSymbol: KtNamedClassOrObjectSymbol, - dri: DRI + dri: DRI, + includeStaticScope: Boolean = true ): DokkaScope { // e.g. getStaticMemberScope contains `valueOf`, `values` and `entries` members for Enum - val scope = listOf(namedClassOrObjectSymbol.getMemberScope(), namedClassOrObjectSymbol.getStaticMemberScope()).asCompositeScope() + val scope = if(includeStaticScope) listOf(namedClassOrObjectSymbol.getMemberScope(), namedClassOrObjectSymbol.getStaticMemberScope()).asCompositeScope() else namedClassOrObjectSymbol.getMemberScope() val constructors = scope.getConstructors().map { visitConstructorSymbol(it) }.toList() val callables = scope.getCallableSymbols().toList() @@ -453,28 +478,18 @@ internal class DokkaSymbolVisitor( } private fun KtAnalysisSession.visitEnumEntrySymbol( - enumEntrySymbol: KtEnumEntrySymbol + enumEntrySymbol: KtEnumEntrySymbol, scope: DokkaScope ): DEnumEntry = withExceptionCatcher(enumEntrySymbol) { val dri = getDRIFromEnumEntry(enumEntrySymbol) val isExpect = false - val scope = enumEntrySymbol.getMemberScope() - val callables = scope.getCallableSymbols().toList() - val classifiers = scope.getClassifierSymbols().toList() - - val functions = callables.filterIsInstance().map { visitFunctionSymbol(it, dri) } - val properties = callables.filterIsInstance().map { visitPropertySymbol(it, dri) } - val classlikes = - classifiers.filterIsInstance() - .map { visitNamedClassOrObjectSymbol(it, dri) } - return DEnumEntry( dri = dri, name = enumEntrySymbol.name.asString(), documentation = getDocumentation(enumEntrySymbol)?.toSourceSetDependent() ?: emptyMap(), - functions = functions, - properties = properties, - classlikes = classlikes, + functions = scope.functions, + properties = scope.properties, + classlikes = emptyList(), // always empty, see https://github.com/Kotlin/dokka/issues/3129 sourceSets = setOf(sourceSet), expectPresentInSet = sourceSet.takeIf { isExpect }, extra = PropertyContainer.withAll( diff --git a/dokka-subprojects/plugin-base/api/base.api b/dokka-subprojects/plugin-base/api/base.api index 360073fe10..788444b93c 100644 --- a/dokka-subprojects/plugin-base/api/base.api +++ b/dokka-subprojects/plugin-base/api/base.api @@ -549,7 +549,6 @@ public final class org/jetbrains/dokka/base/renderers/html/command/consumers/Imm public fun onTagContentEntity (Lkotlinx/html/Entities;)V public fun onTagContentUnsafe (Lkotlin/jvm/functions/Function1;)V public fun onTagEnd (Lkotlinx/html/Tag;)V - public fun onTagError (Lkotlinx/html/Tag;Ljava/lang/Throwable;)V public fun onTagEvent (Lkotlinx/html/Tag;Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V public fun onTagStart (Lkotlinx/html/Tag;)V public final fun processCommand (Lorg/jetbrains/dokka/base/templating/Command;Lkotlin/jvm/functions/Function1;)V diff --git a/dokka-subprojects/plugin-base/src/main/resources/dokka/scripts/platform-content-handler.js b/dokka-subprojects/plugin-base/src/main/resources/dokka/scripts/platform-content-handler.js index 8c4ca53830..811c478883 100644 --- a/dokka-subprojects/plugin-base/src/main/resources/dokka/scripts/platform-content-handler.js +++ b/dokka-subprojects/plugin-base/src/main/resources/dokka/scripts/platform-content-handler.js @@ -18,8 +18,6 @@ const samplesLightThemeName = 'idea' window.addEventListener('load', () => { document.querySelectorAll("div[data-platform-hinted]") .forEach(elem => elem.addEventListener('click', (event) => togglePlatformDependent(event, elem))) - document.querySelectorAll("div[tabs-section]") - .forEach(elem => elem.addEventListener('click', (event) => toggleSectionsEventHandler(event))) const filterSection = document.getElementById('filter-section') if (filterSection) { filterSection.addEventListener('click', (event) => filterButtonHandler(event)) @@ -177,19 +175,30 @@ function handleAnchor() { } function initTabs() { - document.querySelectorAll("div[tabs-section]") - .forEach(element => { - showCorrespondingTabBody(element) - element.addEventListener('click', (event) => toggleSectionsEventHandler(event)) - }) - let cached = localStorage.getItem("active-tab") - if (cached) { - let parsed = JSON.parse(cached) - let tab = document.querySelector('div[tabs-section] > button[data-togglable="' + parsed + '"]') - if (tab) { - toggleSections(tab) - } - } + // we could have only a single type of data - classlike or package + const mainContent = document.querySelector('.main-content'); + const type = mainContent ? mainContent.getAttribute("data-page-type") : null; + const localStorageKey = "active-tab-" + type; + document.querySelectorAll('div[tabs-section]').forEach(element => { + showCorrespondingTabBody(element); + element.addEventListener('click', ({target}) => { + const togglable = target ? target.getAttribute("data-togglable") : null; + if (!togglable) return; + + localStorage.setItem(localStorageKey, JSON.stringify(togglable)); + toggleSections(target); + }); + }); + + const cached = localStorage.getItem(localStorageKey); + if (!cached) return; + + const tab = document.querySelector( + 'div[tabs-section] > button[data-togglable="' + JSON.parse(cached) + '"]' + ); + if (!tab) return; + + toggleSections(tab); } function showCorrespondingTabBody(element) { @@ -293,12 +302,6 @@ function toggleSections(target) { activateTabsBody("tabs-section-body") } -function toggleSectionsEventHandler(evt) { - if (!evt.target.getAttribute("data-togglable")) return - localStorage.setItem('active-tab', JSON.stringify(evt.target.getAttribute("data-togglable"))) - toggleSections(evt.target) -} - function togglePlatformDependent(e, container) { let target = e.target if (target.tagName != 'BUTTON') return; diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/content/HighlightingTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/content/HighlightingTest.kt index 4fe6e20fe8..a7fb2bdea6 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/content/HighlightingTest.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/content/HighlightingTest.kt @@ -15,7 +15,7 @@ class HighlightingTest : BaseAbstractTest() { sourceSets { sourceSet { sourceRoots = listOf("src/") - classpath = listOf(commonStdlibPath!!) + classpath = listOf(commonStdlibPath!!, jvmStdlibPath!!) externalDocumentationLinks = listOf(stdlibExternalDocumentationLink) } } diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/KotlinDeprecatedTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/KotlinDeprecatedTest.kt index 9dfcfed3cf..7612aff8b1 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/KotlinDeprecatedTest.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/KotlinDeprecatedTest.kt @@ -27,6 +27,7 @@ class KotlinDeprecatedTest : BaseAbstractTest() { sourceSets { sourceSet { sourceRoots = listOf("src/") + classpath = listOfNotNull(jvmStdlibPath) analysisPlatform = "jvm" } } diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/SinceKotlinTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/SinceKotlinTest.kt index 8576803c7e..4cb2570441 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/SinceKotlinTest.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/SinceKotlinTest.kt @@ -27,6 +27,7 @@ class SinceKotlinTest : AbstractRenderingTest() { sourceSets { sourceSet { sourceRoots = listOf("src/") + classpath = listOfNotNull(jvmStdlibPath) analysisPlatform = "jvm" } } @@ -185,6 +186,7 @@ class SinceKotlinTest : AbstractRenderingTest() { sourceSets { sourceSet { sourceRoots = listOf("src/") + classpath = listOfNotNull(jvmStdlibPath) analysisPlatform = "jvm" } sourceSet { @@ -193,10 +195,12 @@ class SinceKotlinTest : AbstractRenderingTest() { } sourceSet { sourceRoots = listOf("src/") + classpath = listOfNotNull(commonStdlibPath) analysisPlatform = "common" } sourceSet { sourceRoots = listOf("src/") + classpath = listOfNotNull(jsStdlibPath) analysisPlatform = "js" } sourceSet { diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/content/exceptions/ContentForExceptions.kt b/dokka-subprojects/plugin-base/src/test/kotlin/content/exceptions/ContentForExceptions.kt index cd37d1c4a9..9a9fd8b4c5 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/content/exceptions/ContentForExceptions.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/content/exceptions/ContentForExceptions.kt @@ -10,10 +10,7 @@ import org.jetbrains.dokka.PluginConfigurationImpl import org.jetbrains.dokka.base.DokkaBase import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest import org.jetbrains.dokka.model.DisplaySourceSet -import utils.ParamAttributes -import utils.bareSignature -import utils.findTestType -import utils.OnlyDescriptors +import utils.* import kotlin.test.Test import kotlin.test.assertEquals @@ -22,6 +19,7 @@ class ContentForExceptions : BaseAbstractTest() { sourceSets { sourceSet { sourceRoots = listOf("src/") + classpath = listOfNotNull(jvmStdlibPath) analysisPlatform = "jvm" } } @@ -35,6 +33,7 @@ class ContentForExceptions : BaseAbstractTest() { displayName = "common" analysisPlatform = "common" sourceRoots = listOf("src/commonMain/kotlin/pageMerger/Test.kt") + classpath = listOfNotNull(commonStdlibPath) } sourceSet { name = "jvm" @@ -42,6 +41,7 @@ class ContentForExceptions : BaseAbstractTest() { analysisPlatform = "jvm" dependentSourceSets = setOf(common.value.sourceSetID) sourceRoots = listOf("src/jvmMain/kotlin/pageMerger/Test.kt") + classpath = listOfNotNull(jvmStdlibPath) } sourceSet { name = "linuxX64" @@ -339,6 +339,7 @@ class ContentForExceptions : BaseAbstractTest() { } } + @OnlyDescriptorsMPP("Return type for native `function` should be null rather than kotlin/Unit") @Test fun `throws in merged functions`() { testInline( diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/content/params/ContentForParamsTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/content/params/ContentForParamsTest.kt index aeb7dcf19b..03bc0469b7 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/content/params/ContentForParamsTest.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/content/params/ContentForParamsTest.kt @@ -23,6 +23,7 @@ class ContentForParamsTest : BaseAbstractTest() { sourceSets { sourceSet { sourceRoots = listOf("src/") + classpath = listOfNotNull(jvmStdlibPath) analysisPlatform = "jvm" } } @@ -531,7 +532,7 @@ class ContentForParamsTest : BaseAbstractTest() { link { check { assertEquals( - "java.lang/RuntimeException///PointingToDeclaration/", + "kotlin/RuntimeException///PointingToDeclaration/", (this as ContentDRILink).address.toString() ) } diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/content/seealso/ContentForSeeAlsoTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/content/seealso/ContentForSeeAlsoTest.kt index afcc2d3a02..2790d8b67f 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/content/seealso/ContentForSeeAlsoTest.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/content/seealso/ContentForSeeAlsoTest.kt @@ -17,6 +17,7 @@ class ContentForSeeAlsoTest : BaseAbstractTest() { sourceSets { sourceSet { sourceRoots = listOf("src/") + classpath = listOfNotNull(jvmStdlibPath) analysisPlatform = "jvm" } } @@ -217,6 +218,7 @@ class ContentForSeeAlsoTest : BaseAbstractTest() { } } + @OnlyDescriptors("issue #3179") @Test fun `undocumented seealso with reference to property for class`() { testInline( @@ -310,6 +312,7 @@ class ContentForSeeAlsoTest : BaseAbstractTest() { } } + @OnlyDescriptors("issue #3179") @Test fun `documented seealso with reference to property for class`() { testInline( diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/content/typealiases/TypealiasTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/content/typealiases/TypealiasTest.kt index 6cc9abfe3d..4015e0f402 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/content/typealiases/TypealiasTest.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/content/typealiases/TypealiasTest.kt @@ -18,7 +18,7 @@ class TypealiasTest : BaseAbstractTest() { sourceSets { sourceSet { sourceRoots = listOf("src/") - classpath = listOf(commonStdlibPath!!) + classpath = listOf(commonStdlibPath!!, jvmStdlibPath!!) externalDocumentationLinks = listOf(stdlibExternalDocumentationLink) } } diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/enums/KotlinEnumsTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/enums/KotlinEnumsTest.kt index 48db0d84fd..c32a5cc288 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/enums/KotlinEnumsTest.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/enums/KotlinEnumsTest.kt @@ -15,8 +15,7 @@ import org.jetbrains.dokka.pages.ContentGroup import org.jsoup.Jsoup import org.jsoup.nodes.Element import signatures.renderedContent -import utils.TestOutputWriter -import utils.TestOutputWriterPlugin +import utils.* import java.net.URL import kotlin.test.Test import kotlin.test.assertEquals @@ -292,6 +291,7 @@ class KotlinEnumsTest : BaseAbstractTest() { sourceSets { sourceSet { sourceRoots = listOf("src/") + classpath = listOfNotNull(jvmStdlibPath) } } } @@ -327,6 +327,47 @@ class KotlinEnumsTest : BaseAbstractTest() { } } + @Test + @OnlyDescriptors("K2 has `compareTo`, that should be suppressed, due to #3196") + fun `enum should have functions on page`() { + val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + sourceRoots = listOf("src/") + } + } + } + + testInline( + """ + |/src/main/kotlin/basic/TestEnum.kt + |package testpackage + | + | + |interface Sample { + | fun toBeImplemented(): String + |} + | + |enum class TestEnum: Sample { + | E1 { + | override fun toBeImplemented(): String = "e1" + | } + |} + """.trimMargin(), + configuration + ) { + pagesTransformationStage = { root -> + root.contentPage("E1") { + assertHasFunctions("toBeImplemented") + } + + root.contentPage("TestEnum") { + assertHasFunctions("toBeImplemented", "valueOf", "values") + } + } + } + } + @Test fun enumWithAnnotationsOnEntries() { val configuration = dokkaConfiguration { diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/filter/DeprecationFilterTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/filter/DeprecationFilterTest.kt index cedadaf9f6..75d82e9b07 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/filter/DeprecationFilterTest.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/filter/DeprecationFilterTest.kt @@ -18,6 +18,7 @@ class DeprecationFilterTest : BaseAbstractTest() { sourceSets { sourceSet { sourceRoots = listOf("src/main/kotlin/basic/Test.kt") + classpath = listOfNotNull(jvmStdlibPath) skipDeprecated = false perPackageOptions = mutableListOf( PackageOptionsImpl( diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/filter/VisibilityFilterTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/filter/VisibilityFilterTest.kt index ea9ff326b5..872e58651b 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/filter/VisibilityFilterTest.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/filter/VisibilityFilterTest.kt @@ -691,6 +691,7 @@ class VisibilityFilterTest : BaseAbstractTest() { sourceSet { includeNonPublic = true sourceRoots = listOf("src/main/kotlin/basic/Test.kt") + classpath = listOfNotNull(jvmStdlibPath) } } } diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/renderers/html/TabbedContentTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/renderers/html/TabbedContentTest.kt index 0a748580a6..090127fd39 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/renderers/html/TabbedContentTest.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/renderers/html/TabbedContentTest.kt @@ -25,6 +25,7 @@ class TabbedContentTest : BaseAbstractTest() { private fun Element.getTabbedRow(type: String) = select(".table-row[data-togglable=$type]") private fun Element.getTabbedTable(type: String) = select("div[data-togglable=$type] .table") + private fun Element.getMainContentDataType() = selectFirst(".main-content")?.attr("data-page-type") @Test fun `should have correct tabbed content type`() { @@ -64,6 +65,7 @@ class TabbedContentTest : BaseAbstractTest() { assertEquals(1, classContent.getTabbedTable("TYPE").size) assertEquals(3, classContent.getTabbedRow("EXTENSION_FUNCTION").size) assertEquals(2, classContent.getTabbedRow("EXTENSION_PROPERTY").size) + assertEquals("classlike", classContent.getMainContentDataType()) val packagePage = writerPlugin.writer.renderedContent("root/example/index.html") assertEquals(1, packagePage.getTabbedTable("TYPE").size) @@ -71,6 +73,7 @@ class TabbedContentTest : BaseAbstractTest() { assertEquals(1, packagePage.getTabbedTable("FUNCTION").size) assertEquals(3, packagePage.getTabbedRow("EXTENSION_FUNCTION").size) assertEquals(2, packagePage.getTabbedRow("EXTENSION_PROPERTY").size) + assertEquals("package", packagePage.getMainContentDataType()) } } } diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/signatures/FunctionalTypeConstructorsSignatureTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/signatures/FunctionalTypeConstructorsSignatureTest.kt index 9463e133fd..22807e8757 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/signatures/FunctionalTypeConstructorsSignatureTest.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/signatures/FunctionalTypeConstructorsSignatureTest.kt @@ -20,7 +20,7 @@ class FunctionalTypeConstructorsSignatureTest : BaseAbstractTest() { sourceSets { sourceSet { sourceRoots = listOf("src/") - classpath = listOf(commonStdlibPath!!) + classpath = listOf(commonStdlibPath!!, jvmStdlibPath!!) externalDocumentationLinks = listOf( stdlibExternalDocumentationLink, DokkaConfiguration.ExternalDocumentationLink.Companion.jdk(8) diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/transformers/InheritedEntriesDocumentableFilterTransfromerTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/transformers/InheritedEntriesDocumentableFilterTransfromerTest.kt index 831d2680cd..c07dd5b813 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/transformers/InheritedEntriesDocumentableFilterTransfromerTest.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/transformers/InheritedEntriesDocumentableFilterTransfromerTest.kt @@ -9,7 +9,6 @@ import org.jetbrains.dokka.model.DEnum import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertTrue -import utils.OnlyDescriptors class InheritedEntriesDocumentableFilterTransformerTest : BaseAbstractTest() { val suppressingInheritedConfiguration = dokkaConfiguration { @@ -138,7 +137,6 @@ class InheritedEntriesDocumentableFilterTransformerTest : BaseAbstractTest() { } } - @OnlyDescriptors("Entry does not have `name` and `ordinal`") // TODO @Test fun `should work with enum entries when not suppressing`(){ testInline( @@ -146,7 +144,8 @@ class InheritedEntriesDocumentableFilterTransformerTest : BaseAbstractTest() { /src/suppressed/Suppressed.kt package suppressed enum class Suppressed { - ENTRY_SUPPRESSED + ENTRY_SUPPRESSED; + class A } """.trimIndent(), nonSuppressingInheritedConfiguration diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/transformers/MergeImplicitExpectActualDeclarationsTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/transformers/MergeImplicitExpectActualDeclarationsTest.kt index f7118f335a..18e42e477d 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/transformers/MergeImplicitExpectActualDeclarationsTest.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/transformers/MergeImplicitExpectActualDeclarationsTest.kt @@ -13,10 +13,10 @@ import org.jetbrains.dokka.model.dfs import org.jetbrains.dokka.model.firstChildOfType import org.jetbrains.dokka.pages.* import utils.assertNotNull +import utils.findSectionWithName import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertNotNull -import utils.OnlyDescriptors class MergeImplicitExpectActualDeclarationsTest : BaseAbstractTest() { @@ -52,15 +52,6 @@ class MergeImplicitExpectActualDeclarationsTest : BaseAbstractTest() { ) } - private fun ClasslikePageNode.findSectionWithName(name: String) : ContentNode? { - var sectionHeader: ContentHeader? = null - return content.dfs { node -> - node.children.filterIsInstance().any { header -> - header.children.firstOrNull { it is ContentText && it.text == name }?.also { sectionHeader = header } != null - } - }?.children?.dropWhile { child -> child != sectionHeader }?.drop(1)?.firstOrNull() - } - private fun ContentNode.findTabWithType(type: TabbedContentType): ContentNode? = dfs { node -> node.children.filterIsInstance().any { gr -> gr.extra[TabbedContentTypeExtra]?.value == type @@ -274,7 +265,6 @@ class MergeImplicitExpectActualDeclarationsTest : BaseAbstractTest() { fun PageNode.childrenRec(): List = listOf(this) + children.flatMap { it.childrenRec() } - @OnlyDescriptors("Enum entry [SMTH] does not have functions") // TODO @Test fun `should merge enum entries`() { testInline( @@ -304,7 +294,8 @@ class MergeImplicitExpectActualDeclarationsTest : BaseAbstractTest() { assertNotNull(classPage, "Tested class not found!") val functions = classPage.findSectionWithName("Functions").assertNotNull("Functions") - val method1 = functions.children.singleOrNull().assertNotNull("method1") + val method1 = functions.children.single { it.sourceSets.size == 2 && it.dci.dri.singleOrNull()?.callable?.name == "method1" } + .assertNotNull("method1") assertEquals( 2, diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/utils/contentUtils.kt b/dokka-subprojects/plugin-base/src/test/kotlin/utils/contentUtils.kt index b83d8697bb..3ca0bd2d6c 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/utils/contentUtils.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/utils/contentUtils.kt @@ -5,10 +5,9 @@ package utils import matchers.content.* -import org.jetbrains.dokka.pages.BasicTabbedContentType -import org.jetbrains.dokka.pages.ContentGroup -import org.jetbrains.dokka.pages.ContentPage -import org.jetbrains.dokka.pages.RootPageNode +import org.jetbrains.dokka.model.dfs +import org.jetbrains.dokka.pages.* +import kotlin.test.assertEquals //TODO: Try to unify those functions after update to 1.4 fun ContentMatcherBuilder<*>.functionSignature( @@ -327,6 +326,24 @@ fun ContentMatcherBuilder<*>.unwrapAnnotation(elem: Map.Entry PageNode.contentPage(name: String, block: T.() -> Unit) { + (dfs { it.name == name } as? T).assertNotNull("The page `$name` is not found").block() +} + +fun ClasslikePageNode.assertHasFunctions(vararg expectedFunctionName: String) { + val functions = this.findSectionWithName("Functions").assertNotNull("Functions") + val functionsName = functions.children.map { (it.dfs { it is ContentText } as ContentText).text } + assertEquals(expectedFunctionName.toList(), functionsName) +} + +fun ClasslikePageNode.findSectionWithName(name: String) : ContentNode? { + var sectionHeader: ContentHeader? = null + return content.dfs { node -> + node.children.filterIsInstance().any { header -> + header.children.firstOrNull { it is ContentText && it.text == name }?.also { sectionHeader = header } != null + } + }?.children?.dropWhile { child -> child != sectionHeader }?.drop(1)?.firstOrNull() +} data class ParamAttributes( val annotations: Map>, diff --git a/dokka-subprojects/plugin-javadoc/build.gradle.kts b/dokka-subprojects/plugin-javadoc/build.gradle.kts index 6450c632fa..541de7d1d1 100644 --- a/dokka-subprojects/plugin-javadoc/build.gradle.kts +++ b/dokka-subprojects/plugin-javadoc/build.gradle.kts @@ -17,7 +17,7 @@ dependencies { implementation(projects.pluginKotlinAsJava) implementation(kotlin("reflect")) - implementation(libs.soywiz.korte) + implementation(libs.korlibs.template) implementation(libs.kotlinx.html) implementation(libs.kotlinx.coroutines.core) diff --git a/dokka-subprojects/plugin-javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/KorteJavadocRenderer.kt b/dokka-subprojects/plugin-javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/KorteJavadocRenderer.kt index 658e42ed0d..cfc4bb2a9a 100644 --- a/dokka-subprojects/plugin-javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/KorteJavadocRenderer.kt +++ b/dokka-subprojects/plugin-javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/KorteJavadocRenderer.kt @@ -4,7 +4,7 @@ package org.jetbrains.dokka.javadoc.renderer -import com.soywiz.korte.* +import korlibs.template.* import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch diff --git a/dokka-subprojects/plugin-kotlin-as-java/README.md b/dokka-subprojects/plugin-kotlin-as-java/README.md index b0ec7c8e98..e33bd1bb6d 100644 --- a/dokka-subprojects/plugin-kotlin-as-java/README.md +++ b/dokka-subprojects/plugin-kotlin-as-java/README.md @@ -8,7 +8,7 @@ The Kotlin as Java plugin is published to maven central as a [separate artifact](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-as-java-plugin): ```text -org.jetbrains.dokka:kotlin-as-java-plugin:1.9.0 +org.jetbrains.dokka:kotlin-as-java-plugin:1.9.10 ``` **This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to diff --git a/dokka-subprojects/plugin-mathjax/README.md b/dokka-subprojects/plugin-mathjax/README.md index d9604084b5..a12095eeba 100644 --- a/dokka-subprojects/plugin-mathjax/README.md +++ b/dokka-subprojects/plugin-mathjax/README.md @@ -23,5 +23,5 @@ The MathJax plugin is published to Maven Central as a [separate artifact](https://mvnrepository.com/artifact/org.jetbrains.dokka/mathjax-plugin): ```text -org.jetbrains.dokka:mathjax-plugin:1.9.0 +org.jetbrains.dokka:mathjax-plugin:1.9.10 ``` diff --git a/dokka-subprojects/plugin-versioning/README.md b/dokka-subprojects/plugin-versioning/README.md index be36ef0ee7..d501a58fd1 100644 --- a/dokka-subprojects/plugin-versioning/README.md +++ b/dokka-subprojects/plugin-versioning/README.md @@ -19,7 +19,7 @@ You can apply the versioning plugin the same way as other Dokka plugins: ```kotlin dependencies { - dokkaHtmlPlugin("org.jetbrains.dokka:versioning-plugin:1.9.0") + dokkaHtmlPlugin("org.jetbrains.dokka:versioning-plugin:1.9.10") } ``` @@ -33,7 +33,7 @@ plugin within subprojects as well as in their parent project. ```groovy dependencies { - dokkaHtmlPlugin 'org.jetbrains.dokka:versioning-plugin:1.9.0' + dokkaHtmlPlugin 'org.jetbrains.dokka:versioning-plugin:1.9.10' } ``` @@ -55,7 +55,7 @@ plugin within subprojects as well as in their parent project. org.jetbrains.dokka versioning-plugin - 1.9.0 + 1.9.10 @@ -68,15 +68,15 @@ plugin within subprojects as well as in their parent project.

CLI You can find the versioning plugin's artifact on -[mvnrepository](https://mvnrepository.com/artifact/org.jetbrains.dokka/versioning-plugin/1.9.0) or by browsing -[maven central repository](https://repo1.maven.org/maven2/org/jetbrains/dokka/versioning-plugin/1.9.0) +[mvnrepository](https://mvnrepository.com/artifact/org.jetbrains.dokka/versioning-plugin/1.9.10) or by browsing +[maven central repository](https://repo1.maven.org/maven2/org/jetbrains/dokka/versioning-plugin/1.9.10) directly, and pass it to `pluginsClasspath`. Via command line arguments: ```Bash -java -jar dokka-cli-1.9.0.jar \ - -pluginsClasspath "./dokka-base-1.9.0.jar;...;./versioning-plugin-1.9.0.jar" \ +java -jar dokka-cli-1.9.10.jar \ + -pluginsClasspath "./dokka-base-1.9.10.jar;...;./versioning-plugin-1.9.10.jar" \ ... ``` @@ -86,9 +86,9 @@ Via JSON configuration: { ... "pluginsClasspath": [ - "./dokka-base-1.9.0.jar", + "./dokka-base-1.9.10.jar", "...", - "./versioning-plugin-1.9.0.jar" + "./versioning-plugin-1.9.10.jar" ], ... } @@ -135,7 +135,7 @@ import org.jetbrains.dokka.versioning.VersioningConfiguration buildscript { dependencies { - classpath("org.jetbrains.dokka:versioning-plugin:1.9.0") + classpath("org.jetbrains.dokka:versioning-plugin:1.9.10") } } @@ -232,7 +232,7 @@ dokkaHtml { CLI ```Bash -java -jar dokka-cli-1.9.0.jar \ +java -jar dokka-cli-1.9.10.jar \ ... -pluginsConfiguration "org.jetbrains.dokka.versioning.VersioningPlugin={\"version\": \"1.5\", \"versionsOrdering\": [\"1.5\", \"1.4\", \"1.3\", \"1.2\", \"1.1\", \"alpha-2\", \"alpha-1\"], \"olderVersionsDir\": \"documentation/version\", \"olderVersions\": [\"documentation/alpha/alpha-2\", \"documentation/alpha/alpha-1\"], \"renderVersionsNavigationOnAllPages\": true}" @@ -290,12 +290,12 @@ import org.jetbrains.dokka.versioning.VersioningConfiguration buildscript { dependencies { - classpath("org.jetbrains.dokka:versioning-plugin:1.9.0") + classpath("org.jetbrains.dokka:versioning-plugin:1.9.10") } } dependencies { - dokkaPlugin("org.jetbrains.dokka:versioning-plugin:1.9.0") + dokkaPlugin("org.jetbrains.dokka:versioning-plugin:1.9.10") } tasks.dokkaHtml { diff --git a/examples/gradle/dokka-customFormat-example/build.gradle.kts b/examples/gradle/dokka-customFormat-example/build.gradle.kts index 280b8edbd0..eb647a7e20 100644 --- a/examples/gradle/dokka-customFormat-example/build.gradle.kts +++ b/examples/gradle/dokka-customFormat-example/build.gradle.kts @@ -7,13 +7,13 @@ import org.jetbrains.dokka.base.DokkaBase import org.jetbrains.dokka.base.DokkaBaseConfiguration plugins { - kotlin("jvm") version "1.9.0" - id("org.jetbrains.dokka") version "1.9.0" + kotlin("jvm") version "1.9.10" + id("org.jetbrains.dokka") version "1.9.10" } buildscript { dependencies { - classpath("org.jetbrains.dokka:dokka-base:1.9.0") + classpath("org.jetbrains.dokka:dokka-base:1.9.10") } } diff --git a/examples/gradle/dokka-gradle-example/build.gradle.kts b/examples/gradle/dokka-gradle-example/build.gradle.kts index 0d09f96fe8..330e01046f 100644 --- a/examples/gradle/dokka-gradle-example/build.gradle.kts +++ b/examples/gradle/dokka-gradle-example/build.gradle.kts @@ -6,8 +6,8 @@ import org.jetbrains.dokka.gradle.DokkaTask import java.net.URL plugins { - kotlin("jvm") version "1.9.0" - id("org.jetbrains.dokka") version "1.9.0" + kotlin("jvm") version "1.9.10" + id("org.jetbrains.dokka") version "1.9.10" } repositories { diff --git a/examples/gradle/dokka-kotlinAsJava-example/build.gradle.kts b/examples/gradle/dokka-kotlinAsJava-example/build.gradle.kts index f971188355..83673de772 100644 --- a/examples/gradle/dokka-kotlinAsJava-example/build.gradle.kts +++ b/examples/gradle/dokka-kotlinAsJava-example/build.gradle.kts @@ -3,8 +3,8 @@ */ plugins { - kotlin("jvm") version "1.9.0" - id("org.jetbrains.dokka") version "1.9.0" + kotlin("jvm") version "1.9.10" + id("org.jetbrains.dokka") version "1.9.10" } repositories { @@ -15,11 +15,11 @@ dependencies { testImplementation(kotlin("test-junit")) // Will apply the plugin to all Dokka tasks - dokkaPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.9.0") + dokkaPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.9.10") // Will apply the plugin only to the `:dokkaHtml` task - //dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.9.0") + //dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.9.10") // Will apply the plugin only to the `:dokkaGfm` task - //dokkaGfmPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.9.0") + //dokkaGfmPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.9.10") } diff --git a/examples/gradle/dokka-library-publishing-example/build.gradle.kts b/examples/gradle/dokka-library-publishing-example/build.gradle.kts index 003aa04f46..ac6678e338 100644 --- a/examples/gradle/dokka-library-publishing-example/build.gradle.kts +++ b/examples/gradle/dokka-library-publishing-example/build.gradle.kts @@ -3,8 +3,8 @@ */ plugins { - kotlin("jvm") version "1.9.0" - id("org.jetbrains.dokka") version "1.9.0" + kotlin("jvm") version "1.9.10" + id("org.jetbrains.dokka") version "1.9.10" `java-library` `maven-publish` } diff --git a/examples/gradle/dokka-multimodule-example/gradle.properties b/examples/gradle/dokka-multimodule-example/gradle.properties index fda31413f2..18c74db645 100644 --- a/examples/gradle/dokka-multimodule-example/gradle.properties +++ b/examples/gradle/dokka-multimodule-example/gradle.properties @@ -2,5 +2,5 @@ # Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. # -kotlinVersion=1.9.0 -dokkaVersion=1.9.0 +kotlinVersion=1.9.10 +dokkaVersion=1.9.10 diff --git a/examples/gradle/dokka-multiplatform-example/build.gradle.kts b/examples/gradle/dokka-multiplatform-example/build.gradle.kts index 56c03564c4..df4ea0147f 100644 --- a/examples/gradle/dokka-multiplatform-example/build.gradle.kts +++ b/examples/gradle/dokka-multiplatform-example/build.gradle.kts @@ -8,8 +8,8 @@ import org.jetbrains.dokka.gradle.DokkaTask import org.jetbrains.dokka.Platform plugins { - kotlin("multiplatform") version "1.9.0" - id("org.jetbrains.dokka") version "1.9.0" + kotlin("multiplatform") version "1.9.10" + id("org.jetbrains.dokka") version "1.9.10" } repositories { diff --git a/examples/gradle/dokka-versioning-multimodule-example/build.gradle.kts b/examples/gradle/dokka-versioning-multimodule-example/build.gradle.kts index 3984caa598..88a78e376c 100644 --- a/examples/gradle/dokka-versioning-multimodule-example/build.gradle.kts +++ b/examples/gradle/dokka-versioning-multimodule-example/build.gradle.kts @@ -3,8 +3,8 @@ */ plugins { - kotlin("jvm") version "1.9.0" - id("org.jetbrains.dokka") version "1.9.0" apply false + kotlin("jvm") version "1.9.10" + id("org.jetbrains.dokka") version "1.9.10" apply false } // The versioning plugin must be applied in all submodules @@ -18,6 +18,6 @@ subprojects { } val dokkaPlugin by configurations dependencies { - dokkaPlugin("org.jetbrains.dokka:versioning-plugin:1.9.0") + dokkaPlugin("org.jetbrains.dokka:versioning-plugin:1.9.10") } } diff --git a/examples/gradle/dokka-versioning-multimodule-example/parentProject/build.gradle.kts b/examples/gradle/dokka-versioning-multimodule-example/parentProject/build.gradle.kts index 4bcee1609d..9fc84cbaac 100644 --- a/examples/gradle/dokka-versioning-multimodule-example/parentProject/build.gradle.kts +++ b/examples/gradle/dokka-versioning-multimodule-example/parentProject/build.gradle.kts @@ -8,7 +8,7 @@ import org.jetbrains.dokka.versioning.VersioningConfiguration buildscript { dependencies { - classpath("org.jetbrains.dokka:versioning-plugin:1.9.0") + classpath("org.jetbrains.dokka:versioning-plugin:1.9.10") } repositories { diff --git a/examples/maven/pom.xml b/examples/maven/pom.xml index 811e490236..11a6428b2d 100644 --- a/examples/maven/pom.xml +++ b/examples/maven/pom.xml @@ -12,8 +12,8 @@ kotlin-maven-example 1.0-SNAPSHOT - 1.9.0 - 1.9.0 + 1.9.10 + 1.9.10 diff --git a/examples/plugin/hide-internal-api/README.md b/examples/plugin/hide-internal-api/README.md index f186d2e0c9..d06e97b58b 100644 --- a/examples/plugin/hide-internal-api/README.md +++ b/examples/plugin/hide-internal-api/README.md @@ -1,7 +1,7 @@ # Hide Internal API plugin example This project represents a simple Dokka Plugin that was developed step-by-step in the -[Sample plugin](https://kotlin.github.io/dokka/1.9.0/developer_guide/plugin-development/sample-plugin-tutorial/) +[Sample plugin](https://kotlin.github.io/dokka/1.9.10/developer_guide/plugin-development/sample-plugin-tutorial/) tutorial. This is a frequent request with varying requirements. The plugin excludes any declaration that is marked with `org.jetbrains.dokka.internal.test.Internal` annotation. @@ -9,7 +9,7 @@ The annotation itself is not provided in this project and is instead matched by You can change it to your own internal annotation or to some other marker that suits you. To learn how to install and debug it locally, -[see documentation](https://kotlin.github.io/dokka/1.9.0/developer_guide/plugin-development/sample-plugin-tutorial/#debugging). +[see documentation](https://kotlin.github.io/dokka/1.9.10/developer_guide/plugin-development/sample-plugin-tutorial/#debugging). ___ diff --git a/examples/plugin/hide-internal-api/build.gradle.kts b/examples/plugin/hide-internal-api/build.gradle.kts index bdbf365814..2665101586 100644 --- a/examples/plugin/hide-internal-api/build.gradle.kts +++ b/examples/plugin/hide-internal-api/build.gradle.kts @@ -7,8 +7,8 @@ import org.jetbrains.kotlin.gradle.tasks.KotlinCompile import java.net.URI plugins { - kotlin("jvm") version "1.9.0" - id("org.jetbrains.dokka") version "1.9.0" + kotlin("jvm") version "1.9.10" + id("org.jetbrains.dokka") version "1.9.10" `maven-publish` signing } diff --git a/examples/plugin/hide-internal-api/gradle.properties b/examples/plugin/hide-internal-api/gradle.properties index 40669a3870..a3f59a072e 100644 --- a/examples/plugin/hide-internal-api/gradle.properties +++ b/examples/plugin/hide-internal-api/gradle.properties @@ -2,4 +2,4 @@ # Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. # -dokkaVersion=1.9.0 +dokkaVersion=1.9.10 diff --git a/gradle.properties b/gradle.properties index 8f23dc5df4..e1bbd2bb07 100644 --- a/gradle.properties +++ b/gradle.properties @@ -3,7 +3,7 @@ # # Project Settings -dokka_version=1.9.10-SNAPSHOT +dokka_version=1.9.20-SNAPSHOT org.jetbrains.dokka.javaToolchain.mainCompiler=8 org.jetbrains.dokka.javaToolchain.testLauncher=8 org.jetbrains.dokka.kotlinLanguageLevel=1.4 diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 05a1faf28e..9a25490b73 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -3,15 +3,15 @@ gradlePlugin-kotlin = "1.9.10" # See: https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin gradlePlugin-android = "4.2.2" -gradlePlugin-dokka = "1.9.0" +gradlePlugin-dokka = "1.9.10" -kotlinx-coroutines = "1.6.3" -kotlinx-collections-immutable = "0.3.4" -kotlinx-bcv = "0.12.1" +kotlinx-coroutines = "1.7.3" +kotlinx-collections-immutable = "0.3.6" +kotlinx-bcv = "0.13.2" ## Analysis kotlin-compiler = "1.9.10" -kotlin-compiler-k2 = "1.9.0-release-358" +kotlin-compiler-k2 = "1.9.30-dev-3330" # MUST match the version of the intellij platform used in the kotlin compiler, # otherwise this will lead to different versions of psi API and implementations @@ -20,10 +20,10 @@ kotlin-compiler-k2 = "1.9.0-release-358" intellij-platform = "213.7172.25" ## HTML -jsoup = "1.15.3" -freemarker = "2.3.31" -soywiz-korte = "2.7.0" -kotlinx-html = "0.7.5" +jsoup = "1.16.1" +freemarker = "2.3.32" +korlibs-template = "4.0.10" +kotlinx-html = "0.9.1" ## Markdown jetbrains-markdown = "0.3.1" @@ -39,7 +39,7 @@ apacheMaven-archiver = "2.5" apacheMaven-pluginTools = "3.5.2" ## CLI -kotlinx-cli = "0.3.4" +kotlinx-cli = "0.3.6" ## NPM | Frontend node = "16.13.0" @@ -51,8 +51,8 @@ gradlePlugin-gradlePluginPublish = "0.20.0" gradlePlugin-gradleNode = "3.5.1" ## Test -junit = "5.9.2" -eclipse-jgit = "5.12.0.202106070339-r" +junit = "5.9.3" +eclipse-jgit = "5.13.2.202306221912-r" # jgit 6.X requires Java 11 to run [libraries] @@ -62,6 +62,7 @@ kotlinx-collections-immutable = { module = "org.jetbrains.kotlinx:kotlinx-collec #### Gradle plugins #### # The Maven coordinates of Gradle plugins that are either used in convention plugins, or in Dokka subprojects gradlePlugin-kotlin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "gradlePlugin-kotlin" } +gradlePlugin-kotlin-klibCommonizerApi = { module = "org.jetbrains.kotlin:kotlin-klib-commonizer-api", version.ref = "gradlePlugin-kotlin" } gradlePlugin-android = { module = "com.android.tools.build:gradle", version.ref = "gradlePlugin-android" } gradlePlugin-dokka = { module = "org.jetbrains.dokka:dokka-gradle-plugin", version.ref = "gradlePlugin-dokka" } gradlePlugin-shadow = { module = "gradle.plugin.com.github.johnrengelman:shadow", version.ref = "gradlePlugin-shadow" } @@ -93,7 +94,10 @@ intellij-platform-util-rt = { module = "com.jetbrains.intellij.platform:util-rt" jsoup = { module = "org.jsoup:jsoup", version.ref = "jsoup" } freemarker = { module = "org.freemarker:freemarker", version.ref = "freemarker" } kotlinx-html = { module = "org.jetbrains.kotlinx:kotlinx-html-jvm", version.ref = "kotlinx-html" } -soywiz-korte = { module = "com.soywiz.korlibs.korte:korte-jvm", version.ref = "soywiz-korte" } + +# for korlibs-template: the package was renamed and the library's source was moved, but the artifact name is still old, +# so there's a mismatch. might change in the future, follow https://github.com/korlibs/korge/issues/1836 for updates +korlibs-template = { module = "com.soywiz.korlibs.korte:korte-jvm", version.ref = "korlibs-template" } #### Markdown #### jetbrains-markdown = { module = "org.jetbrains:markdown", version.ref = "jetbrains-markdown" }