Repository: Kotlin/dokka (kotlin)

Issue:
[K2] Support generating documentation for stdlib
Currently, it is blocked by #3137 and _(possible)_ https://youtrack.jetbrains.com/issue/KT-56076/K2-build-Kotlin-standard-library

StdLib is a specific Kotlin library that can require supporting extra flags to analyse and build the documentation. For example, in Dokka K1 the flag `ignoreCommonBuiltIns` should be enabled to analyse stdlib.

Dokka K2 should have the possibility to generate correct documentation for stdlib.
The result documentation should have no difference from the output generated by Dokka K1.



**Technical details**

It can require enabling `AnalysisFlags.allowKotlinPackage ` in the Analysis API. Also, extra analysis flags can be needed.

Pull request description:
StdLib should copy some source and sample files to avoid [#3701](https://github.com/Kotlin/dokka/issues/3701).
Also, generating documentation works well with the fix for https://youtrack.jetbrains.com/issue/KT-74740. However, to have the fix, Dokka needs to update AA - #3951, which is currently blocked.

Patch:
diff --git a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/InternalConfiguration.kt b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/InternalConfiguration.kt
new file mode 100644
index 0000000000..57f4fba01f
--- /dev/null
+++ b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/InternalConfiguration.kt
@@ -0,0 +1,24 @@
+/*
+ * Copyright 2014-2025 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.analysis.kotlin.symbols.plugin
+
+// revisit in scope of https://github.com/Kotlin/dokka/issues/2776
+internal object InternalConfiguration {
+    private const val ALLOW_KOTLIN_PACKAGE_PROPERTY = "org.jetbrains.dokka.analysis.allowKotlinPackage"
+
+    /**
+     * Allow analysing code in the 'kotlin' package
+     *
+     * Default: false
+     *
+     * @see org.jetbrains.kotlin.config.AnalysisFlags.allowKotlinPackage
+     */
+    val allowKotlinPackage: Boolean
+        get() = getBooleanProperty(ALLOW_KOTLIN_PACKAGE_PROPERTY)
+
+    private fun getBooleanProperty(propertyName: String): Boolean {
+        return System.getProperty(propertyName) in setOf("1", "true")
+    }
+}
\ No newline at end of file
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 eca0847bf4..3c05644ea1 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
@@ -49,6 +49,7 @@ internal fun getLanguageVersionSettings(
     return LanguageVersionSettingsImpl(
         languageVersion = languageVersion,
         apiVersion = apiVersion, analysisFlags = hashMapOf(
+            AnalysisFlags.allowKotlinPackage to InternalConfiguration.allowKotlinPackage,
             // special flag for Dokka
             // force to resolve light classes (lazily by default)
             AnalysisFlags.eagerResolveOfLightClasses to true


Test patch:
diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/transformers/ObviousAndInheritedFunctionsDocumentableFilterTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/transformers/ObviousAndInheritedFunctionsDocumentableFilterTest.kt
index bf39a16e89..3436d96d3c 100644
--- a/dokka-subprojects/plugin-base/src/test/kotlin/transformers/ObviousAndInheritedFunctionsDocumentableFilterTest.kt
+++ b/dokka-subprojects/plugin-base/src/test/kotlin/transformers/ObviousAndInheritedFunctionsDocumentableFilterTest.kt
@@ -9,7 +9,7 @@ import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
 import org.junit.jupiter.params.ParameterizedTest
 import org.junit.jupiter.params.provider.MethodSource
 import testApi.testRunner.dokkaConfiguration
-import utils.OnlyDescriptors
+import utils.withAllowKotlinPackage
 import kotlin.test.assertEquals
 
 class ObviousAndInheritedFunctionsDocumentableFilterTest : BaseAbstractTest() {
@@ -252,12 +252,12 @@ class ObviousAndInheritedFunctionsDocumentableFilterTest : BaseAbstractTest() {
         }
     }
 
-    @OnlyDescriptors("#3354")
     @ParameterizedTest
     @MethodSource(value = ["suppressingObviousConfiguration"])
-    fun `should not suppress toString, equals and hashcode of kotlin Any`(suppressingConfiguration: DokkaConfigurationImpl) {
-        testInline(
-            """
+    fun `should not suppress toString, equals and hashcode of kotlin Any`(suppressingConfiguration: DokkaConfigurationImpl) =
+        withAllowKotlinPackage {
+            testInline(
+                """
             /src/Any.kt
             package kotlin
             public open class Any {
@@ -266,22 +266,21 @@ class ObviousAndInheritedFunctionsDocumentableFilterTest : BaseAbstractTest() {
                 public open fun toString(): String
             }
             """.trimIndent(),
-            suppressingConfiguration
-        ) {
-            preMergeDocumentablesTransformationStage = { modules ->
-                val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions }
-                assertEquals(setOf("equals", "hashCode", "toString"), functions.map { it.name }.toSet())
+                suppressingConfiguration
+            ) {
+                preMergeDocumentablesTransformationStage = { modules ->
+                    val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions }
+                    assertEquals(setOf("equals", "hashCode", "toString"), functions.map { it.name }.toSet())
+                }
             }
         }
-    }
 
-    // when running with K2 - kotlin package is skipped
-    @OnlyDescriptors("#3354")
     @ParameterizedTest
     @MethodSource(value = ["suppressingObviousConfiguration"])
-    fun `should not suppress toString, equals and hashcode of kotlin Enum`(suppressingConfiguration: DokkaConfigurationImpl) {
-        testInline(
-            """
+    fun `should not suppress toString, equals and hashcode of kotlin Enum`(suppressingConfiguration: DokkaConfigurationImpl) =
+        withAllowKotlinPackage {
+            testInline(
+                """
             /src/Enum.kt
             package kotlin
             public abstract class Enum<E : Enum<E>>(name: String, ordinal: Int): Comparable<E> {
@@ -291,12 +290,16 @@ class ObviousAndInheritedFunctionsDocumentableFilterTest : BaseAbstractTest() {
                 public override fun toString(): String
             }
             """.trimIndent(),
-            suppressingConfiguration
-        ) {
-            preMergeDocumentablesTransformationStage = { modules ->
-                val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions }
-                assertEquals(setOf("compareTo", "equals", "hashCode", "toString"), functions.map { it.name }.toSet())
+                suppressingConfiguration
+            ) {
+                preMergeDocumentablesTransformationStage = { modules ->
+                    val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions }
+                    assertEquals(
+                        setOf("compareTo", "equals", "hashCode", "toString"),
+                        functions.map { it.name }.toSet()
+                    )
+                }
             }
+
         }
-    }
 }
diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/utils/systemProperties.kt b/dokka-subprojects/plugin-base/src/test/kotlin/utils/systemProperties.kt
index 36c9ecce8a..6016937db7 100644
--- a/dokka-subprojects/plugin-base/src/test/kotlin/utils/systemProperties.kt
+++ b/dokka-subprojects/plugin-base/src/test/kotlin/utils/systemProperties.kt
@@ -14,6 +14,13 @@ internal fun withAllTypesPage(block: () -> Unit): Unit =
 internal fun withSinceKotlin(block: () -> Unit): Unit =
     DokkaBaseInternalConfiguration.withProperty(SHOULD_DISPLAY_SINCE_KOTLIN_SYS_PROP, "true", block)
 
+/**
+ * This property works only for K2
+ * Allow analysing code in the 'kotlin' package
+ */
+internal fun withAllowKotlinPackage(block: () -> Unit): Unit =
+    DokkaBaseInternalConfiguration.withProperty("org.jetbrains.dokka.analysis.allowKotlinPackage", "true", block)
+
 internal fun DokkaBaseInternalConfiguration.withProperty(propertyName: String, value: String, block: () -> Unit) {
     setProperty(propertyName, value)
     try {