Update Analysis API to 2.1.20-dev-4370 (#3802)

dokka-integration-tests/gradle/src/testTemplateProjectTasksExecutionStress/kotlin/SequentialTasksExecutionStressTest.kt

@@ -25,7 +25,10 @@ class SequentialTasksExecutionStressTest : AbstractGradleIntegrationTest() {
             buildVersions,
             "runTasks",
             "-Ptask_number=$iterations",
-            jvmArgs = listOf("-Xmx1G", "-XX:MaxMetaspaceSize=500m"),
+            jvmArgs = listOf(
+                "-Xmx1G", "-XX:MaxMetaspaceSize=500m",
+                "-XX:SoftRefLRUPolicyMSPerMB=10" // to free up the metaspace on JVM 8, see https://youtrack.jetbrains.com/issue/KT-55831/
+            ),
             enableBuildCache = false,
         ).buildRelaxed()
 

dokka-subprojects/analysis-java-psi/api/analysis-java-psi.api

@@ -26,6 +26,7 @@ public final class org/jetbrains/dokka/analysis/java/ExceptionJavadocTag$Compani
 
 public final class org/jetbrains/dokka/analysis/java/JavaAnalysisPlugin : org/jetbrains/dokka/plugability/DokkaPlugin {
 	public fun <init> ()V
+	public final fun disposeGlobalStandaloneApplicationServices ()V
 	public final fun getDocCommentCreators ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;
 	public final fun getDocCommentFinder ()Lorg/jetbrains/dokka/analysis/java/doccomment/DocCommentFinder;
 	public final fun getDocCommentParsers ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;

dokka-subprojects/analysis-java-psi/src/main/kotlin/org/jetbrains/dokka/analysis/java/JavaAnalysisPlugin.kt

@@ -71,6 +71,21 @@ public class JavaAnalysisPlugin : DokkaPlugin() {
         DocCommentFinder(logger, docCommentFactory)
     }
 
+    // TODO #3936(https://youtrack.jetbrains.com/issue/KT-71862) use an endpoint from AA
+    /**
+     * Disposes global resources which would persist after unloading Analysis API (Symbols analysis) and IJ platform classes.
+     *
+     * **Important:** Once this function has been called, Analysis API *and* IntelliJ platform classes should not be used anymore. The classes
+     * should either be unloaded or the whole program should be shut down.
+     *
+     * Note: Disposing of resources, including threads, allows unloading Dokka's class loader.
+     */
+    @InternalDokkaApi
+    public fun disposeGlobalStandaloneApplicationServices() {
+        @Suppress("UnstableApiUsage")
+        com.intellij.util.concurrency.AppExecutorUtil.shutdownApplicationScheduledExecutorService()
+    }
+
     internal val javaDocCommentCreator by extending {
         docCommentCreators providing { JavaDocCommentCreator() }
     }

dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfigurationMapper.kt

@@ -82,7 +82,7 @@ fun TestDokkaConfiguration.toDokkaConfiguration(projectDir: File): DokkaConfigur
         override val suppressInheritedMembers: Boolean
             get() = throw NotImplementedError("Not expected to be used by analysis modules")
         override val finalizeCoroutines: Boolean
-            get() = throw NotImplementedError("Not expected to be used by analysis modules")
+            get() = false
     }
 }
 

dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/SymbolsAnalysisPlugin.kt

@@ -20,10 +20,7 @@ import org.jetbrains.dokka.analysis.kotlin.symbols.services.*
 import org.jetbrains.dokka.analysis.kotlin.symbols.services.KotlinDocumentableSourceLanguageParser
 import org.jetbrains.dokka.analysis.kotlin.symbols.services.SymbolExternalDocumentablesProvider
 import org.jetbrains.dokka.analysis.kotlin.symbols.translators.DefaultSymbolToDocumentableTranslator
-import org.jetbrains.dokka.plugability.DokkaPlugin
-import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
-import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
-import org.jetbrains.dokka.plugability.querySingle
+import org.jetbrains.dokka.plugability.*
 import org.jetbrains.dokka.renderers.PostAction
 import org.jetbrains.kotlin.asJava.elements.KtLightAbstractAnnotation
 
@@ -42,7 +39,14 @@ public class SymbolsAnalysisPlugin : DokkaPlugin() {
     }
 
     internal val disposeKotlinAnalysisPostAction by extending {
-        CoreExtensions.postActions with PostAction { querySingle { kotlinAnalysis }.close() }
+        CoreExtensions.postActions providing { context ->
+            PostAction {
+                querySingle { kotlinAnalysis }.close()
+                if (context.configuration.finalizeCoroutines)
+                    // TODO #3936(https://youtrack.jetbrains.com/issue/KT-71862)  use an endpoint from AA
+                    javaAnalysisPlugin.disposeGlobalStandaloneApplicationServices()
+            }
+        }
     }
 
     internal val symbolToDocumentableTranslator by extending {

dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/configuration.kt

@@ -147,17 +147,22 @@ public interface DokkaConfiguration : Serializable {
     /**
      * Whether coroutines dispatchers should be shutdown after
      * generating documentation via [DokkaGenerator.generate].
+     * Additionally, whether the Analysis API and IJ platform global
+     * services should be shutdown.
      *
-     * It effectively stops all background threads associated with
+     * If this is enabled, Coroutines *and* the Analysis API *and* IntelliJ
+     * platform classes should no longer be used after the documentation is generated once.
+     *
+     * For example, it effectively stops all background threads associated with
      * coroutines in order to make classes unloadable by the JVM,
      * and rejects all new tasks with [RejectedExecutionException]
      *
-     * This is primarily useful for multi-module builds where coroutines
+     * This is primarily useful for multi-module builds where global services
      * can be shut down after each module's partial task to avoid
      * possible memory leaks.
      *
      * However, this can lead to problems in specific lifecycles where
-     * coroutines are shared and will be reused after documentation generation,
+     * global services are shared and will be reused after documentation generation,
      * and closing it down will leave the build in an inoperable state.
      * One such example is unit tests, for which finalization should be disabled.
      */

gradle/libs.versions.toml

@@ -16,7 +16,7 @@ javaDiffUtils = "4.12"
 
 ## Analysis
 kotlin-compiler = "2.0.20"
-kotlin-compiler-k2 = "2.1.0-dev-5441"
+kotlin-compiler-k2 = "2.1.20-dev-4370"
 
 # 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