From 1671c41652bf8f32807e05f0dd9d23f922fd4437 Mon Sep 17 00:00:00 2001 From: Yahor Berdnikau Date: Mon, 11 Sep 2023 14:39:21 +0200 Subject: [PATCH] [Gradle] Update KDoc for Kapt extension ^KT-58858 In Progress --- .../api/kotlin-gradle-plugin-api.api | 7 ++ .../kotlin/gradle/dsl/KaptExtensionConfig.kt | 95 +++++++++++++++---- 2 files changed, 83 insertions(+), 19 deletions(-) diff --git a/libraries/tools/kotlin-gradle-plugin-api/api/kotlin-gradle-plugin-api.api b/libraries/tools/kotlin-gradle-plugin-api/api/kotlin-gradle-plugin-api.api index 4c8528ff7d2..630b45a478b 100644 --- a/libraries/tools/kotlin-gradle-plugin-api/api/kotlin-gradle-plugin-api.api +++ b/libraries/tools/kotlin-gradle-plugin-api/api/kotlin-gradle-plugin-api.api @@ -119,6 +119,7 @@ public abstract interface class org/jetbrains/kotlin/gradle/dsl/KaptExtensionCon public abstract fun annotationProcessor (Ljava/lang/String;)V public abstract fun annotationProcessors ([Ljava/lang/String;)V public abstract fun arguments (Lkotlin/jvm/functions/Function1;)V + public abstract fun arguments (Lorg/gradle/api/Action;)V public abstract fun getCorrectErrorTypes ()Z public abstract fun getDetectMemoryLeaks ()Ljava/lang/String; public abstract fun getDumpDefaultParameterValues ()Z @@ -132,6 +133,7 @@ public abstract interface class org/jetbrains/kotlin/gradle/dsl/KaptExtensionCon public abstract fun getUseBuildCache ()Z public abstract fun getUseLightAnalysis ()Z public abstract fun javacOptions (Lkotlin/jvm/functions/Function1;)V + public abstract fun javacOptions (Lorg/gradle/api/Action;)V public abstract fun setCorrectErrorTypes (Z)V public abstract fun setDetectMemoryLeaks (Ljava/lang/String;)V public abstract fun setDumpDefaultParameterValues (Z)V @@ -145,6 +147,11 @@ public abstract interface class org/jetbrains/kotlin/gradle/dsl/KaptExtensionCon public abstract fun setUseLightAnalysis (Z)V } +public final class org/jetbrains/kotlin/gradle/dsl/KaptExtensionConfig$DefaultImpls { + public static fun arguments (Lorg/jetbrains/kotlin/gradle/dsl/KaptExtensionConfig;Lorg/gradle/api/Action;)V + public static fun javacOptions (Lorg/jetbrains/kotlin/gradle/dsl/KaptExtensionConfig;Lorg/gradle/api/Action;)V +} + public abstract interface class org/jetbrains/kotlin/gradle/dsl/KaptJavacOption { public abstract fun option (Ljava/lang/Object;)V public abstract fun option (Ljava/lang/Object;Ljava/lang/Object;)V diff --git a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KaptExtensionConfig.kt b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KaptExtensionConfig.kt index 5e5fbb1979b..44c6cf7d104 100644 --- a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KaptExtensionConfig.kt +++ b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KaptExtensionConfig.kt @@ -5,65 +5,102 @@ package org.jetbrains.kotlin.gradle.dsl +import org.gradle.api.Action + /** - * DSL extension used to configure KAPT stub generation and KAPT annotation processing. + * A plugin DSL extension for configuring kapt annotation processing. + * + * Use the extension in your build script in the `kapt` block: + * ```kotlin + * kapt { + * // Your extension configuration + * } + * ``` + * + * See also [Kapt compiler plugin documentation](https://kotlinlang.org/docs/kapt.html). */ interface KaptExtensionConfig { /** - * If `true`, compile classpath should be used to search for annotation processors. + * Also loads annotation processors from compile classpath. + * + * Default: `null` */ var includeCompileClasspath: Boolean? /** - * If `true`, skip body analysis if possible. + * Skips analyzing code bodies, if possible. + * + * Default: `true` */ var useLightAnalysis: Boolean /** - * If `true`, replace generated or error types with ones from the generated sources. + * Replaces any generated error types with error types from the generated sources. + * + * Default: `false` */ var correctErrorTypes: Boolean /** - * If `true`, put initializers on fields when corresponding primary constructor parameters have a default value specified. + * Adds initializers to fields whose corresponding primary constructor parameters have a default value specified. + * + * Default: `false` */ var dumpDefaultParameterValues: Boolean /** - * If `true`, map diagnostic reported on kapt stubs to original locations in Kotlin sources. + * Maps diagnostics reported on kapt stubs to their original locations in Kotlin sources. + * + * Default: `false` */ var mapDiagnosticLocations: Boolean /** - * If `true`, show errors on incompatibilities during stub generation. + * Reports any incompatibility errors found during stub generation. + * + * Default: `false` */ var strictMode: Boolean /** - * If `true`, strip @Metadata annotations from stubs. + * Strips `@Metadata` annotations from stubs. + * + * Default: `false` */ var stripMetadata: Boolean /** - * If `true`, show annotation processor stats. + * Shows annotation processor statistics in the verbose kapt log output. + * + * Default: `false` */ var showProcessorStats: Boolean /** - * If `true`, detect memory leaks in annotation processors. + * Detects memory leaks in annotation processors. + * + * Possible values: "default", "paranoid", "none". + * + * Default: `default` */ var detectMemoryLeaks: String /** - * Opt-out switch for Kapt caching. Should be used when annotation processors used by this project are suspected of - * using anything aside from the task inputs in their logic and are not guaranteed to produce the same - * output on subsequent runs without input changes. + * Uses the [Gradle build cache](https://docs.gradle.org/current/userguide/build_cache.html) feature for kapt tasks. + * + * Set to `false` only when annotation processors used by this project are: + * * suspected of using other sources asides from the task inputs in their processing logic + * * not guaranteed to produce the same output on subsequent runs without input changes. + * + * Default: `true` */ var useBuildCache: Boolean /** - * If true keeps annotation processors added via `annotationProcessor(..)` configuration for javac java-files compilation + * Keeps annotation processors that are added via the `annotationProcessor(..)` configuration for javac java-files compilation + * + * Default: `false` */ var keepJavacAnnotationProcessors: Boolean @@ -83,39 +120,59 @@ interface KaptExtensionConfig { fun arguments(action: KaptArguments.() -> Unit) /** - * Configure [KaptJavacOption] used for annotation processing. + * Configures the [KaptArguments] used for annotation processing. + */ + fun arguments(action: Action) { + arguments { action.execute(this) } + } + + /** + * Configures the [KaptJavacOption] used for annotation processing. */ fun javacOptions(action: KaptJavacOption.() -> Unit) /** - * Gets all javac options used for KAPT. + * Configures the [KaptJavacOption] used for annotation processing. + */ + fun javacOptions(action: Action) { + javacOptions { action.execute(this) } + } + + /** + * Gets all the javac options used to run kapt annotation processing. */ fun getJavacOptions(): Map } /** - * Interface used to specify arguments that are used during KAPT processing. + * A DSL to specify arguments that are used during kapt processing. */ interface KaptArguments { /** * Adds argument with the specified name and values. + * + * Expected [name] and [values] type is [String]. */ fun arg(name: Any, vararg values: Any) } /** - * Interface used to specify javac options that are used during KAPT processing. + * A DSL to specify javac options that are used during kapt processing. */ interface KaptJavacOption { /** * Adds an option with name and value. + * + * Expected [name] and [value] type is [String]. */ fun option(name: Any, value: Any) /** - * Adds an option with name only (no value associated). + * Adds an option with name only. + * + * Expected [name] type is [String]. */ fun option(name: Any) }