[Gradle] Add a check that KGP API has consistent KDoc

^KT-58858 In Progress

generators/tests/org/jetbrains/kotlin/generators/arguments/GenerateGradleOptions.kt

@@ -47,6 +47,14 @@ private const val OPTIONS_PACKAGE_PREFIX = "org.jetbrains.kotlin.gradle.dsl"
 private const val IMPLEMENTATION_SUFFIX = "Default"
 private const val IMPLEMENTATION_HELPERS_SUFFIX = "Helper"
 
+private const val TOOL_OPTIONS_KDOC = "Common options for all Kotlin platforms' compilations and tools."
+private const val COMMON_COMPILER_OPTIONS_KDOC = "Common compiler options for all Kotlin platforms."
+private const val JVM_COMPILER_OPTIONS_KDOC = "Compiler options for Kotlin/JVM."
+private const val JS_COMPILER_OPTIONS_KDOC = "Compiler options for Kotlin/JS."
+private const val NATIVE_COMPILER_OPTIONS_KDOC = "Compiler options for Kotlin Native."
+private const val MULTIPLATFORM_COMPILER_OPTION_KDOC = "Compiler options for the Kotlin common platform."
+private const val JS_DCE_TOOL_OPTIONS_KDOC = "Options for the Kotlin JavaScript dead code elimination tool."
+
 fun generateKotlinGradleOptions(withPrinterToFile: (targetFile: File, Printer.() -> Unit) -> Unit) {
     val apiSrcDir = File(GRADLE_API_SRC_DIR)
     val srcDir = File(GRADLE_PLUGIN_SRC_DIR)
@@ -158,7 +166,8 @@ private fun generateKotlinCommonToolOptions(
     withPrinterToFile(fileFromFqName(apiSrcDir, commonInterfaceFqName)) {
         generateInterface(
             commonInterfaceFqName,
-            commonOptions + additionalOptions
+            commonOptions + additionalOptions,
+            interfaceKDoc = TOOL_OPTIONS_KDOC,
         )
     }
 
@@ -169,6 +178,7 @@ private fun generateKotlinCommonToolOptions(
             commonInterfaceFqName,
             commonOptions + additionalOptions,
             parentType = null,
+            interfaceKDoc = TOOL_OPTIONS_KDOC,
         )
     }
 
@@ -223,6 +233,7 @@ private fun generateKotlinCommonOptions(
             commonCompilerInterfaceFqName,
             commonCompilerOptions,
             parentType = commonToolGeneratedOptions.optionsName,
+            interfaceKDoc = COMMON_COMPILER_OPTIONS_KDOC,
         )
     }
 
@@ -232,7 +243,8 @@ private fun generateKotlinCommonOptions(
             deprecatedCommonCompilerInterfaceFqName,
             commonCompilerInterfaceFqName,
             commonCompilerOptions,
-            parentType = commonToolGeneratedOptions.deprecatedOptionsName
+            parentType = commonToolGeneratedOptions.deprecatedOptionsName,
+            interfaceKDoc = COMMON_COMPILER_OPTIONS_KDOC,
         )
     }
 
@@ -289,6 +301,7 @@ private fun generateKotlinJvmOptions(
             jvmInterfaceFqName,
             jvmOptions,
             parentType = commonCompilerGeneratedOptions.optionsName,
+            interfaceKDoc = JVM_COMPILER_OPTIONS_KDOC,
         )
     }
 
@@ -298,7 +311,8 @@ private fun generateKotlinJvmOptions(
             deprecatedJvmInterfaceFqName,
             jvmInterfaceFqName,
             jvmOptions,
-            parentType = commonCompilerGeneratedOptions.deprecatedOptionsName
+            parentType = commonCompilerGeneratedOptions.deprecatedOptionsName,
+            interfaceKDoc = JVM_COMPILER_OPTIONS_KDOC,
         )
     }
 
@@ -353,6 +367,7 @@ private fun generateKotlinJsOptions(
             jsInterfaceFqName,
             jsOptions,
             parentType = commonCompilerOptions.optionsName,
+            interfaceKDoc = JS_COMPILER_OPTIONS_KDOC,
         )
     }
 
@@ -363,6 +378,7 @@ private fun generateKotlinJsOptions(
             jsInterfaceFqName,
             jsOptions,
             parentType = commonCompilerOptions.deprecatedOptionsName,
+            interfaceKDoc = JS_COMPILER_OPTIONS_KDOC,
         )
     }
 
@@ -417,6 +433,7 @@ private fun generateKotlinNativeOptions(
             nativeInterfaceFqName,
             nativeOptions,
             parentType = commonCompilerOptions.optionsName,
+            interfaceKDoc = NATIVE_COMPILER_OPTIONS_KDOC
         )
     }
 
@@ -472,6 +489,7 @@ private fun generateJsDceOptions(
             jsDceInterfaceFqName,
             jsDceOptions,
             parentType = commonToolOptions.optionsName,
+            interfaceKDoc = JS_DCE_TOOL_OPTIONS_KDOC,
         )
     }
 
@@ -482,6 +500,7 @@ private fun generateJsDceOptions(
             jsDceInterfaceFqName,
             jsDceOptions,
             parentType = commonToolOptions.deprecatedOptionsName,
+            interfaceKDoc = JS_DCE_TOOL_OPTIONS_KDOC,
         )
     }
 
@@ -536,6 +555,7 @@ private fun generateMultiplatformCommonOptions(
             multiplatformCommonInterfaceFqName,
             multiplatformCommonOptions,
             parentType = commonCompilerOptions.optionsName,
+            interfaceKDoc = MULTIPLATFORM_COMPILER_OPTION_KDOC,
         )
     }
 
@@ -545,7 +565,8 @@ private fun generateMultiplatformCommonOptions(
             deprecatedMultiplatformCommonInterfaceFqName,
             multiplatformCommonInterfaceFqName,
             parentType = commonCompilerOptions.deprecatedOptionsName,
-            properties = multiplatformCommonOptions
+            properties = multiplatformCommonOptions,
+            interfaceKDoc = MULTIPLATFORM_COMPILER_OPTION_KDOC,
         )
     }
 
@@ -613,9 +634,10 @@ private fun Printer.generateInterface(
     type: FqName,
     properties: List<KProperty1<*, *>>,
     parentType: FqName? = null,
+    interfaceKDoc: String? = null,
 ) {
     val afterType = parentType?.let { " : $it" }
-    generateDeclaration("interface", type, afterType = afterType) {
+    generateDeclaration("interface", type, afterType = afterType, declarationKDoc = interfaceKDoc) {
         for (property in properties) {
             println()
             generateDoc(property)
@@ -629,6 +651,7 @@ private fun Printer.generateDeprecatedInterface(
     type: FqName,
     compilerOptionType: FqName,
     properties: List<KProperty1<*, *>>,
+    interfaceKDoc: String? = null,
     parentType: FqName? = null,
 ) {
     val afterType = parentType?.let { " : $it" }
@@ -639,8 +662,11 @@ private fun Printer.generateDeprecatedInterface(
     val deprecatedProperties = properties.filter { it.generateDeprecatedKotlinOption }
     // KotlinMultiplatformCommonOptions doesn't have any options, but it is being kept for backward compatibility
     if (deprecatedProperties.isNotEmpty() || type.asString().endsWith("KotlinMultiplatformCommonOptions")) {
-        generateDeclaration(modifier, type, afterType = afterType) {
+        generateDeclaration(modifier, type, afterType = afterType, declarationKDoc = interfaceKDoc) {
 
+            println("/**")
+            println(" * @suppress")
+            println(" */")
             println("${if (parentType != null) "override " else ""}val options: $compilerOptionType")
             deprecatedProperties
                 .forEach {
@@ -761,6 +787,7 @@ internal fun Printer.generateDeclaration(
     modifiers: String,
     type: FqName,
     constructorDeclaration: String? = null,
+    declarationKDoc: String? = null,
     afterType: String? = null,
     generateBody: Printer.() -> Unit
 ) {
@@ -778,6 +805,14 @@ internal fun Printer.generateDeclaration(
         println("package ${type.parent()}")
         println()
     }
+
+    if (declarationKDoc != null) {
+        println("/**")
+        declarationKDoc.split('\n').forEach {
+            println(" * $it")
+        }
+        println(" */")
+    }
     print("$modifiers ${type.shortName()}")
     constructorDeclaration?.let { print(" $it ") }
     afterType?.let { print("$afterType") }

libraries/tools/kotlin-gradle-plugin-api/build.gradle.kts

@@ -7,7 +7,17 @@ plugins {
 configureDokkaPublication(
     shouldLinkGradleApi = true,
     configurePublishingToKotlinlang = true,
-)
+) {
+    dokkaSourceSets.configureEach {
+        reportUndocumented.set(true)
+        failOnWarning.set(true)
+
+        perPackageOption {
+            matchingRegex.set("org\\.jetbrains\\.kotlin\\.gradle\\.plugin.*")
+            suppress.set(true)
+        }
+    }
+}
 
 dependencies {
     commonApi(platform(project(":kotlin-gradle-plugins-bom")))

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinCommonCompilerOptions.kt

@@ -5,6 +5,9 @@
 
 package org.jetbrains.kotlin.gradle.dsl
 
+/**
+ * Common compiler options for all Kotlin platforms.
+ */
 interface KotlinCommonCompilerOptions : org.jetbrains.kotlin.gradle.dsl.KotlinCommonCompilerToolOptions {
 
     /**

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinCommonCompilerToolOptions.kt

@@ -5,6 +5,9 @@
 
 package org.jetbrains.kotlin.gradle.dsl
 
+/**
+ * Common options for all Kotlin platforms' compilations and tools.
+ */
 interface KotlinCommonCompilerToolOptions {
 
     /**

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinCommonOptions.kt

@@ -5,7 +5,13 @@
 
 package org.jetbrains.kotlin.gradle.dsl
 
+/**
+ * Common compiler options for all Kotlin platforms.
+ */
 interface KotlinCommonOptions : org.jetbrains.kotlin.gradle.dsl.KotlinCommonToolOptions {
+    /**
+     * @suppress
+     */
     override val options: org.jetbrains.kotlin.gradle.dsl.KotlinCommonCompilerOptions
 
     private val kotlin.String?.apiVersionCompilerOption get() = if (this != null) org.jetbrains.kotlin.gradle.dsl.KotlinVersion.fromVersion(this) else null

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinCommonToolOptions.kt

@@ -5,7 +5,13 @@
 
 package org.jetbrains.kotlin.gradle.dsl
 
+/**
+ * Common options for all Kotlin platforms' compilations and tools.
+ */
 interface KotlinCommonToolOptions {
+    /**
+     * @suppress
+     */
     val options: org.jetbrains.kotlin.gradle.dsl.KotlinCommonCompilerToolOptions
 
     /**

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinJsCompilerOptions.kt

@@ -5,6 +5,9 @@
 
 package org.jetbrains.kotlin.gradle.dsl
 
+/**
+ * Compiler options for Kotlin/JS.
+ */
 interface KotlinJsCompilerOptions : org.jetbrains.kotlin.gradle.dsl.KotlinCommonCompilerOptions {
 
     /**

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinJsDceCompilerToolOptions.kt

@@ -5,6 +5,9 @@
 
 package org.jetbrains.kotlin.gradle.dsl
 
+/**
+ * Options for the Kotlin JavaScript dead code elimination tool.
+ */
 interface KotlinJsDceCompilerToolOptions : org.jetbrains.kotlin.gradle.dsl.KotlinCommonCompilerToolOptions {
 
     /**

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinJsDceOptions.kt

@@ -5,7 +5,13 @@
 
 package org.jetbrains.kotlin.gradle.dsl
 
+/**
+ * Options for the Kotlin JavaScript dead code elimination tool.
+ */
 interface KotlinJsDceOptions : org.jetbrains.kotlin.gradle.dsl.KotlinCommonToolOptions {
+    /**
+     * @suppress
+     */
     override val options: org.jetbrains.kotlin.gradle.dsl.KotlinJsDceCompilerToolOptions
 
     /**

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinJsOptions.kt

@@ -5,7 +5,13 @@
 
 package org.jetbrains.kotlin.gradle.dsl
 
+/**
+ * Compiler options for Kotlin/JS.
+ */
 interface KotlinJsOptions : org.jetbrains.kotlin.gradle.dsl.KotlinCommonOptions {
+    /**
+     * @suppress
+     */
     override val options: org.jetbrains.kotlin.gradle.dsl.KotlinJsCompilerOptions
 
     /**

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinJvmCompilerOptions.kt

@@ -5,6 +5,9 @@
 
 package org.jetbrains.kotlin.gradle.dsl
 
+/**
+ * Compiler options for Kotlin/JVM.
+ */
 interface KotlinJvmCompilerOptions : org.jetbrains.kotlin.gradle.dsl.KotlinCommonCompilerOptions {
 
     /**

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinJvmOptions.kt

@@ -5,7 +5,13 @@
 
 package org.jetbrains.kotlin.gradle.dsl
 
+/**
+ * Compiler options for Kotlin/JVM.
+ */
 interface KotlinJvmOptions : org.jetbrains.kotlin.gradle.dsl.KotlinCommonOptions {
+    /**
+     * @suppress
+     */
     override val options: org.jetbrains.kotlin.gradle.dsl.KotlinJvmCompilerOptions
 
     /**

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinMultiplatformCommonCompilerOptions.kt

@@ -5,5 +5,8 @@
 
 package org.jetbrains.kotlin.gradle.dsl
 
+/**
+ * Compiler options for the Kotlin common platform.
+ */
 interface KotlinMultiplatformCommonCompilerOptions : org.jetbrains.kotlin.gradle.dsl.KotlinCommonCompilerOptions {
 }

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinMultiplatformCommonOptions.kt

@@ -5,6 +5,12 @@
 
 package org.jetbrains.kotlin.gradle.dsl
 
+/**
+ * Compiler options for the Kotlin common platform.
+ */
 interface KotlinMultiplatformCommonOptions : org.jetbrains.kotlin.gradle.dsl.KotlinCommonOptions {
+    /**
+     * @suppress
+     */
     override val options: org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformCommonCompilerOptions
 }

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinNativeCompilerOptions.kt

@@ -5,6 +5,9 @@
 
 package org.jetbrains.kotlin.gradle.dsl
 
+/**
+ * Compiler options for Kotlin Native.
+ */
 interface KotlinNativeCompilerOptions : org.jetbrains.kotlin.gradle.dsl.KotlinCommonCompilerOptions {
 
     /**

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/tasks/KotlinTaskConfigs.kt

@@ -67,9 +67,19 @@ interface KotlinCompileTool : PatternFilterable, Task {
     @get:OutputDirectory
     val destinationDirectory: DirectoryProperty
 
+    /**
+     * Returns the set of exclude patterns.
+     *
+     * @return The exclude patterns. Returns an empty set when there are no exclude patterns.
+     */
     @Internal
     override fun getExcludes(): MutableSet<String>
 
+    /**
+     * Returns the set of include patterns.
+     *
+     * @return The include patterns. Returns an empty set when there are no include patterns.
+     */
     @Internal
     override fun getIncludes(): MutableSet<String>
 }

repo/gradle-build-conventions/buildsrc-compat/src/main/kotlin/GradleCommon.kt

@@ -664,6 +664,7 @@ fun Project.addBomCheckTask() {
 fun Project.configureDokkaPublication(
     shouldLinkGradleApi: Boolean = false,
     configurePublishingToKotlinlang: Boolean = false,
+    additionalDokkaTaskConfiguration: DokkaTask.() -> Unit = {}
 ) {
 
     val dokkaVersioningPluginVersion = "1.8.10"
@@ -715,6 +716,8 @@ fun Project.configureDokkaPublication(
                         }
                     }
                 }
+
+                additionalDokkaTaskConfiguration()
             }
 
             tasks.named<Jar>(variantSourceSet.javadocJarTaskName) {
@@ -764,6 +767,8 @@ fun Project.configureDokkaPublication(
                             }
                         }
                     }
+
+                    additionalDokkaTaskConfiguration()
                 }
             }
         }