From bd24810ec8204cc9423de69c6b4c8a959e89c93c Mon Sep 17 00:00:00 2001
From: "Dmitriy.Panov" <dmitriy.panov@jetbrains.com>
Date: Wed, 2 Apr 2025 21:52:08 +0200
Subject: [PATCH] IJI-2358 an option to generate Maven artifacts documentation
 with Dokka

(cherry picked from commit 1d45e3a101acc23c503939d5a4be1af70c60921f)

IJ-MR-159792

GitOrigin-RevId: 24bd2a0272183669f478a8cfe9697abdd6194516
---
 .idea/modules.xml                             |  1 +
 libraries/dokka/README.md                     |  2 +
 libraries/dokka/intellij.libraries.dokka.iml  | 86 +++++++++++++++++++
 .../build/MavenArtifactsProperties.kt         |  3 +
 .../intellij/build/impl/maven/Dokka.kt        | 84 ++++++++++++++++++
 .../build/impl/maven/MavenArtifactsBuilder.kt | 11 +++
 6 files changed, 187 insertions(+)
 create mode 100644 libraries/dokka/README.md
 create mode 100644 libraries/dokka/intellij.libraries.dokka.iml
 create mode 100644 platform/build-scripts/src/org/jetbrains/intellij/build/impl/maven/Dokka.kt

diff --git a/.idea/modules.xml b/.idea/modules.xml
index c4be54c09d05..c8c15315a9c9 100644
--- a/.idea/modules.xml
+++ b/.idea/modules.xml
@@ -544,6 +544,7 @@
       <module fileurl="file://$PROJECT_DIR$/platform/libraries/cglib/intellij.libraries.cglib.iml" filepath="$PROJECT_DIR$/platform/libraries/cglib/intellij.libraries.cglib.iml" />
       <module fileurl="file://$PROJECT_DIR$/libraries/compose-desktop/intellij.libraries.compose.desktop.iml" filepath="$PROJECT_DIR$/libraries/compose-desktop/intellij.libraries.compose.desktop.iml" />
       <module fileurl="file://$PROJECT_DIR$/libraries/compose-foundation-desktop/intellij.libraries.compose.foundation.desktop.iml" filepath="$PROJECT_DIR$/libraries/compose-foundation-desktop/intellij.libraries.compose.foundation.desktop.iml" />
+      <module fileurl="file://$PROJECT_DIR$/libraries/dokka/intellij.libraries.dokka.iml" filepath="$PROJECT_DIR$/libraries/dokka/intellij.libraries.dokka.iml" />
       <module fileurl="file://$PROJECT_DIR$/libraries/grpc/intellij.libraries.grpc.iml" filepath="$PROJECT_DIR$/libraries/grpc/intellij.libraries.grpc.iml" />
       <module fileurl="file://$PROJECT_DIR$/libraries/grpc-netty-shaded/intellij.libraries.grpc.netty.shaded.iml" filepath="$PROJECT_DIR$/libraries/grpc-netty-shaded/intellij.libraries.grpc.netty.shaded.iml" />
       <module fileurl="file://$PROJECT_DIR$/libraries/junit4/intellij.libraries.junit4.iml" filepath="$PROJECT_DIR$/libraries/junit4/intellij.libraries.junit4.iml" />
diff --git a/libraries/dokka/README.md b/libraries/dokka/README.md
new file mode 100644
index 000000000000..97dd83af0ab4
--- /dev/null
+++ b/libraries/dokka/README.md
@@ -0,0 +1,2 @@
+This module is required to resolve all the dependencies for [Dokka CLI](https://kotlinlang.org/docs/dokka-cli.html).
+It's being used in https://github.com/JetBrains/intellij-community/tree/master/platform/build-scripts/src/org/jetbrains/intellij/build/impl/maven/Dokka.kt to generate Javadoc for Maven Central publication.
\ No newline at end of file
diff --git a/libraries/dokka/intellij.libraries.dokka.iml b/libraries/dokka/intellij.libraries.dokka.iml
new file mode 100644
index 000000000000..ca2005dd1754
--- /dev/null
+++ b/libraries/dokka/intellij.libraries.dokka.iml
@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="JAVA_MODULE" version="4">
+  <component name="NewModuleRootManager" inherit-compiler-output="true">
+    <exclude-output />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+    <orderEntry type="module-library" scope="PROVIDED">
+      <library name="jetbrains.dokka.cli" type="repository">
+        <properties maven-id="org.jetbrains.dokka:dokka-cli:2.0.0">
+          <verification>
+            <artifact url="file://$MAVEN_REPOSITORY$/org/jetbrains/dokka/dokka-cli/2.0.0/dokka-cli-2.0.0.jar">
+              <sha256sum>5f70f358160b48ef9763b2ced4e96037f1bfc8d0122de692550ca320ab4b9f20</sha256sum>
+            </artifact>
+          </verification>
+        </properties>
+        <CLASSES>
+          <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/dokka/dokka-cli/2.0.0/dokka-cli-2.0.0.jar!/" />
+        </CLASSES>
+        <JAVADOC />
+        <SOURCES />
+      </library>
+    </orderEntry>
+    <orderEntry type="module-library" scope="PROVIDED">
+      <library name="jetbrains.dokka.javadoc.plugin" type="repository">
+        <properties maven-id="org.jetbrains.dokka:javadoc-plugin:2.0.0">
+          <verification>
+            <artifact url="file://$MAVEN_REPOSITORY$/org/jetbrains/dokka/javadoc-plugin/2.0.0/javadoc-plugin-2.0.0.jar">
+              <sha256sum>41055e59e3f0a6e04b77557641b9a2db0311e99f81c5bc7b1fcc3409bb23d99b</sha256sum>
+            </artifact>
+            <artifact url="file://$MAVEN_REPOSITORY$/org/jetbrains/dokka/dokka-base/2.0.0/dokka-base-2.0.0.jar">
+              <sha256sum>0411d1c38a1d100cbd346c6340c3c4b5f154a48a9c119ed11893d6fae94c91aa</sha256sum>
+            </artifact>
+            <artifact url="file://$MAVEN_REPOSITORY$/org/freemarker/freemarker/2.3.32/freemarker-2.3.32.jar">
+              <sha256sum>04d65ec1bde6cea20e3495d5e78ef96ab774d9936434861d3254bd88e7e94f92</sha256sum>
+            </artifact>
+            <artifact url="file://$MAVEN_REPOSITORY$/org/jetbrains/dokka/kotlin-as-java-plugin/2.0.0/kotlin-as-java-plugin-2.0.0.jar">
+              <sha256sum>3d8931b3c03f84edbf72f67348265205d819d327bb110043ab11d840d59bde41</sha256sum>
+            </artifact>
+            <artifact url="file://$MAVEN_REPOSITORY$/com/soywiz/korlibs/korte/korte-jvm/4.0.10/korte-jvm-4.0.10.jar">
+              <sha256sum>b9b983817a80dbb5f9b599b508616115c1e8e1e3f1fccc301695f4530792690f</sha256sum>
+            </artifact>
+            <artifact url="file://$MAVEN_REPOSITORY$/org/jetbrains/kotlinx/kotlinx-html-jvm/0.9.1/kotlinx-html-jvm-0.9.1.jar">
+              <sha256sum>b68f39cd9ad7b46de0a0e77e7f5908d4e7661f3d0c85d2d9171543fcd5b156fb</sha256sum>
+            </artifact>
+          </verification>
+          <exclude>
+            <dependency maven-id="org.jetbrains.kotlin:kotlin-stdlib" />
+            <dependency maven-id="org.jetbrains.dokka:analysis-markdown" />
+            <dependency maven-id="org.jetbrains.kotlin:kotlin-reflect" />
+            <dependency maven-id="org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm" />
+            <dependency maven-id="org.jsoup:jsoup" />
+            <dependency maven-id="com.fasterxml.jackson.module:jackson-module-kotlin" />
+            <dependency maven-id="org.jetbrains.kotlin:kotlin-stdlib-jdk8" />
+            <dependency maven-id="org.jetbrains.kotlin:kotlin-stdlib-common" />
+          </exclude>
+        </properties>
+        <CLASSES>
+          <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/dokka/javadoc-plugin/2.0.0/javadoc-plugin-2.0.0.jar!/" />
+          <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/dokka/dokka-base/2.0.0/dokka-base-2.0.0.jar!/" />
+          <root url="jar://$MAVEN_REPOSITORY$/org/freemarker/freemarker/2.3.32/freemarker-2.3.32.jar!/" />
+          <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/dokka/kotlin-as-java-plugin/2.0.0/kotlin-as-java-plugin-2.0.0.jar!/" />
+          <root url="jar://$MAVEN_REPOSITORY$/com/soywiz/korlibs/korte/korte-jvm/4.0.10/korte-jvm-4.0.10.jar!/" />
+          <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlinx/kotlinx-html-jvm/0.9.1/kotlinx-html-jvm-0.9.1.jar!/" />
+        </CLASSES>
+        <JAVADOC />
+        <SOURCES />
+      </library>
+    </orderEntry>
+    <orderEntry type="module-library" scope="PROVIDED">
+      <library name="jetbrains.dokka.analysis.kotlin.descriptors" type="repository">
+        <properties maven-id="org.jetbrains.dokka:analysis-kotlin-descriptors:2.0.0">
+          <verification>
+            <artifact url="file://$MAVEN_REPOSITORY$/org/jetbrains/dokka/analysis-kotlin-descriptors/2.0.0/analysis-kotlin-descriptors-2.0.0.jar">
+              <sha256sum>829788c40891a2a3c4b9435cb9ec80d645560d926e9fbbd08ccc29e8e4f1eb7c</sha256sum>
+            </artifact>
+          </verification>
+        </properties>
+        <CLASSES>
+          <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/dokka/analysis-kotlin-descriptors/2.0.0/analysis-kotlin-descriptors-2.0.0.jar!/" />
+        </CLASSES>
+        <JAVADOC />
+        <SOURCES />
+      </library>
+    </orderEntry>
+  </component>
+</module>
\ No newline at end of file
diff --git a/platform/build-scripts/src/org/jetbrains/intellij/build/MavenArtifactsProperties.kt b/platform/build-scripts/src/org/jetbrains/intellij/build/MavenArtifactsProperties.kt
index bbd047b22e72..f0f307181fc5 100644
--- a/platform/build-scripts/src/org/jetbrains/intellij/build/MavenArtifactsProperties.kt
+++ b/platform/build-scripts/src/org/jetbrains/intellij/build/MavenArtifactsProperties.kt
@@ -47,4 +47,7 @@ class MavenArtifactsProperties {
   var publishSourcesFilter: (JpsModule, BuildContext) -> Boolean = { module, context ->
     module.contentRootsList.urls.all { Path.of(JpsPathUtil.urlToPath(it)).startsWith(context.paths.communityHomeDir) }
   }
+
+  @ApiStatus.Internal
+  var isJavadocJarRequired: (JpsModule) -> Boolean = { false }
 }
diff --git a/platform/build-scripts/src/org/jetbrains/intellij/build/impl/maven/Dokka.kt b/platform/build-scripts/src/org/jetbrains/intellij/build/impl/maven/Dokka.kt
new file mode 100644
index 000000000000..bb53c95645db
--- /dev/null
+++ b/platform/build-scripts/src/org/jetbrains/intellij/build/impl/maven/Dokka.kt
@@ -0,0 +1,84 @@
+// Copyright 2000-2025 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
+package org.jetbrains.intellij.build.impl.maven
+
+import org.jetbrains.intellij.build.BuildContext
+import org.jetbrains.intellij.build.io.runProcess
+import org.jetbrains.intellij.build.telemetry.TraceManager.spanBuilder
+import org.jetbrains.intellij.build.telemetry.use
+import org.jetbrains.jps.model.library.JpsLibrary
+import org.jetbrains.jps.model.library.JpsOrderRootType
+import org.jetbrains.jps.model.module.JpsModule
+import java.nio.file.Path
+import kotlin.io.path.ExperimentalPathApi
+import kotlin.io.path.absolutePathString
+import kotlin.io.path.createDirectories
+import kotlin.io.path.deleteRecursively
+import kotlin.io.path.listDirectoryEntries
+
+/**
+ * Both Javadoc and KDoc are processed, see https://kotlinlang.org/docs/dokka-introduction.html
+ */
+@OptIn(ExperimentalPathApi::class)
+internal class Dokka(private val context: BuildContext) {
+  private val moduleWithDokka: JpsModule by lazy {
+    context.findRequiredModule("intellij.libraries.dokka")
+  }
+
+  private fun JpsModule.requireLibrary(name: String): JpsLibrary {
+    return libraryCollection.findLibrary(name) ?: error("Missing library $name for module ${this.name}")
+  }
+
+  /**
+   * See https://kotlinlang.org/docs/dokka-cli.html
+   */
+  private val cli: Path by lazy {
+    val lib = moduleWithDokka.requireLibrary("jetbrains.dokka.cli")
+    val jars = lib.getPaths(JpsOrderRootType.COMPILED)
+    jars.singleOrNull() ?: error("Only one jar is expected in ${lib.name} but found $jars")
+  }
+
+  /**
+   * See https://kotlinlang.org/docs/dokka-javadoc.html
+   */
+  private val pluginsClasspath: List<Path> by lazy {
+    val dokkaJavadoc = moduleWithDokka.requireLibrary("jetbrains.dokka.javadoc.plugin")
+    val dokkaKotlin = moduleWithDokka.requireLibrary("jetbrains.dokka.analysis.kotlin.descriptors")
+    dokkaJavadoc.getPaths(JpsOrderRootType.COMPILED) +
+    dokkaKotlin.getPaths(JpsOrderRootType.COMPILED)
+  }
+
+  /**
+   * @return [outputDir] containing all the docs generated
+   */
+  suspend fun generateDocumentation(
+    modules: List<JpsModule>,
+    outputDir: Path = context.paths.tempDir.resolve("${modules.joinToString(separator = "-") { it.name }}-dokka"),
+  ): Path {
+    return spanBuilder("generate documentation").setAttribute("modules", modules.joinToString { it.name }).use {
+      require(modules.any()) {
+        "No modules supplied to generate Dokka documentation"
+      }
+      outputDir.deleteRecursively()
+      outputDir.createDirectories()
+      val sourceSet = modules.asSequence()
+        .flatMap { it.sourceRoots }
+        .joinToString(prefix = "-src ", separator = ";") {
+          it.path.absolutePathString()
+        }
+      runProcess(
+        args = listOf(
+          context.stableJavaExecutable.absolutePathString(),
+          "-jar", cli.absolutePathString(),
+          "-sourceSet", sourceSet,
+          "-outputDir", outputDir.absolutePathString(),
+          "-loggingLevel", "WARN",
+          "-pluginsClasspath", pluginsClasspath.joinToString(separator = ";") { it.absolutePathString() },
+        )
+      )
+      check(outputDir.listDirectoryEntries(glob = "index.html").any()) {
+        "$outputDir contains no index.html"
+      }
+      outputDir
+    }
+  }
+}
\ No newline at end of file
diff --git a/platform/build-scripts/src/org/jetbrains/intellij/build/impl/maven/MavenArtifactsBuilder.kt b/platform/build-scripts/src/org/jetbrains/intellij/build/impl/maven/MavenArtifactsBuilder.kt
index d4c52ecc4b70..ed287e41e963 100644
--- a/platform/build-scripts/src/org/jetbrains/intellij/build/impl/maven/MavenArtifactsBuilder.kt
+++ b/platform/build-scripts/src/org/jetbrains/intellij/build/impl/maven/MavenArtifactsBuilder.kt
@@ -429,6 +429,17 @@ private suspend fun layoutMavenArtifacts(modulesToPublish: Map<MavenArtifactData
             compress = true,
           )
         }
+        if (context.productProperties.mavenArtifacts.isJavadocJarRequired(artifactData.module)) {
+          check(modulesWithSources.any()) {
+            "No modules with sources found in $modules, a documentation cannot be generated"
+          }
+          val docsFolder = Dokka(context).generateDocumentation(modules = modulesWithSources)
+          buildJar(
+            targetFile = artifactDir.resolve(artifactData.coordinates.getFileName("javadoc", "jar")),
+            sources = listOf(DirSource(docsFolder)),
+            compress = true,
+          )
+        }
       }
     }
   }