azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
^KT-58858 In Progress
This commit is contained in:
Yahor Berdnikau
2023-09-13 17:50:30 +02:00
committed by Space Team
parent 01e9ad1680
commit aeaaf6dd8e
17 changed files with 124 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
generators/tests/org/jetbrains/kotlin/generators/arguments/GenerateGradleOptions.kt
+41 -6
View File
@@ -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
+11 -1
View File
@@ -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
+3
View File
@@ -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
+3
View File
@@ -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
+6
View File
@@ -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
+6
View File
@@ -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
+3
View File
@@ -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
+3
View File
@@ -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
+6
View File
@@ -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
+6
View File
@@ -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
+3
View File
@@ -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
+6
View File
@@ -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
+3
View File
@@ -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
+6
View File
@@ -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
+3
View File
@@ -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
+10
View File
@@ -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
+5
View File
@@ -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()
}
}
}