[Gradle] Update documentation for Kotlin tasks

^KT-58858 In Progress

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

@@ -19,7 +19,14 @@ import org.jetbrains.kotlin.gradle.dsl.*
 import org.jetbrains.kotlin.gradle.dsl.jvm.JvmTargetValidationMode
 import org.jetbrains.kotlin.gradle.plugin.CompilerPluginConfig
 
+/**
+ * Represents a Kotlin task participating in some stage of the build by compiling sources or running additional Kotlin tools.
+ */
 interface KotlinCompileTool : PatternFilterable, Task {
+
+    /**
+     * The configured task inputs (for example, Kotlin sources) which are used to produce a task artifact.
+     */
     @get:InputFiles
     @get:SkipWhenEmpty
     @get:IgnoreEmptyDirectories
@@ -28,21 +35,35 @@ interface KotlinCompileTool : PatternFilterable, Task {
     val sources: FileCollection
 
     /**
-     * Sets sources for this task.
-     * The given sources object is evaluated as per [org.gradle.api.Project.files].
+     * Adds input sources for this task.
+     *
+     * @param sources object is evaluated as per [org.gradle.api.Project.files].
      */
     fun source(vararg sources: Any)
 
     /**
-     * Sets sources for this task.
-     * The given sources object is evaluated as per [org.gradle.api.Project.files].
+     * Sets input sources for this task.
+     *
+     * **Note**: due to [a bug](https://youtrack.jetbrains.com/issue/KT-59632/KotlinCompileTool.setSource-should-replace-existing-sources),
+     * the `setSource()` function does not update already added sources.
+     *
+     * @param sources object is evaluated as per [org.gradle.api.Project.files].
      */
     fun setSource(vararg sources: Any)
 
+    /**
+     * Collection of external artifacts participating in the output artifact generation.
+     *
+     * For example, a Kotlin/JVM compilation task has external JAR files or an
+     * external location with already compiled class files.
+     */
     @get:Classpath
     @get:Incremental
     val libraries: ConfigurableFileCollection
 
+    /**
+     * The destination directory where the task artifact can be found.
+     */
     @get:OutputDirectory
     val destinationDirectory: DirectoryProperty
 
@@ -53,36 +74,68 @@ interface KotlinCompileTool : PatternFilterable, Task {
     override fun getIncludes(): MutableSet<String>
 }
 
+/**
+ * Represents any Kotlin compilation task including common task inputs.
+ */
 interface BaseKotlinCompile : KotlinCompileTool {
 
+    /**
+     * Paths to the output directories of the friend modules whose internal declarations should be visible.
+     */
     @get:Internal
     val friendPaths: ConfigurableFileCollection
 
+    /**
+     * Kotlin compiler plugins artifacts
+     * , such as JAR or class files, that participate in the compilation process. All files that are permitted in the [JVM classpath](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/classpath.html) are permitted here.
+     */
     @get:Classpath
     val pluginClasspath: ConfigurableFileCollection
 
+    /**
+     * The configuration for the Kotlin compiler plugin added in [pluginClasspath] using [CompilerPluginConfig].
+     */
+    @get:Nested
+    val pluginOptions: ListProperty<CompilerPluginConfig>
+
+    // Exists only to be used in 'KotlinCompileCommon' task.
+    // Should be removed once 'moduleName' will be moved into CommonCompilerArguments
+    /**
+     * @suppress
+     */
     @get:Input
     val moduleName: Property<String>
 
+    /**
+     * Specifies the name of [org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet] that is compiled.
+     */
     @get:Internal
     val sourceSetName: Property<String>
 
+    /**
+     * Enables the [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform-mobile-getting-started.html) flag for compilation.
+     */
     @get:Input
     val multiPlatformEnabled: Property<Boolean>
 
+    /**
+     * Enable more granular tracking of inter-modules as part of incremental compilation. Useful in Android projects.
+     */
     @get:Input
     val useModuleDetection: Property<Boolean>
-
-    @get:Nested
-    val pluginOptions: ListProperty<CompilerPluginConfig>
 }
 
-@Suppress("TYPEALIAS_EXPANSION_DEPRECATION")
+/**
+ * Represents a Kotlin task compiling given Kotlin sources into JVM class files.
+ */
 interface KotlinJvmCompile : BaseKotlinCompile,
     KotlinCompileDeprecated<KotlinJvmOptionsDeprecated>,
     KotlinCompilationTask<KotlinJvmCompilerOptions>,
     UsesKotlinJavaToolchain {
 
+    /**
+     * @suppress
+     */
     @get:Deprecated(
         message = "Please migrate to compilerOptions.moduleName",
         replaceWith = ReplaceWith("compilerOptions.moduleName")
@@ -91,6 +144,9 @@ interface KotlinJvmCompile : BaseKotlinCompile,
     @get:Input
     override val moduleName: Property<String>
 
+    /**
+     * @suppress
+     */
     // JVM specific
     @get:Internal("Takes part in compiler args.")
     @Deprecated(
@@ -102,18 +158,18 @@ interface KotlinJvmCompile : BaseKotlinCompile,
     /**
      * Controls JVM target validation mode between this task and the Java compilation task from Gradle for the same source set.
      *
-     * The same JVM targets ensure that the produced jar file contains class files of the same JVM bytecode version,
-     * which is important to avoid compatibility issues for the code consumers.
+     * Using the same JVM targets ensures that the produced JAR file contains class files of the same JVM bytecode version,
+     * which is important to avoid compatibility issues for users of your code.
      *
-     * Also, Gradle Java compilation task [org.gradle.api.tasks.compile.JavaCompile.targetCompatibility] controls value
-     * of "org.gradle.jvm.version" [attribute](https://docs.gradle.org/current/javadoc/org/gradle/api/attributes/java/TargetJvmVersion.html)
-     * which itself controls the produced artifact minimal supported JVM version via
+     * The Gradle Java compilation task [org.gradle.api.tasks.compile.JavaCompile.targetCompatibility] controls the value
+     * of the `org.gradle.jvm.version` [attribute](https://docs.gradle.org/current/javadoc/org/gradle/api/attributes/java/TargetJvmVersion.html)
+     * which itself controls the produced artifact's minimum supported JVM version via
      * [Gradle Module Metadata](https://docs.gradle.org/current/userguide/publishing_gradle_module_metadata.html).
-     * This allows Gradle to check compatibility of dependencies at dependency resolution time.
+     * This allows Gradle to check the compatibility of dependencies at dependency resolution time.
      *
-     * To avoid problems with different targets we advise to use [JDK Toolchain](https://kotl.in/gradle/jvm/toolchain) feature.
+     * To avoid problems with different targets, we advise using the [JVM Toolchain](https://kotl.in/gradle/jvm/toolchain) feature.
      *
-     * Default value for builds with Gradle <8.0 is [JvmTargetValidationMode.WARNING],
+     * The default value for builds with Gradle <8.0 is [JvmTargetValidationMode.WARNING],
      * while for builds with Gradle 8.0+ it is [JvmTargetValidationMode.ERROR].
      *
      * @since 1.9.0
@@ -122,13 +178,35 @@ interface KotlinJvmCompile : BaseKotlinCompile,
     val jvmTargetValidationMode: Property<JvmTargetValidationMode>
 }
 
+/**
+ * Represents a Kotlin task that generates stubs from Java annotation processing results.
+ *
+ * This task generates annotation processing output stubs (without the actual method implementations)
+ * using Java source code.
+ * These generated stubs can be referenced in Kotlin source code compilation before completing
+ * annotation processing.
+ *
+ * This task is a part of [Kotlin/Kapt](https://kotlinlang.org/docs/kapt.html).
+ */
 interface KaptGenerateStubs : KotlinJvmCompile {
+    /**
+     * The directory where generated stubs can be found.
+     */
     @get:OutputDirectory
     val stubsDir: DirectoryProperty
 
+    /**
+     * Allows adding artifacts (accepted by [JVM classpath](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/classpath.html))
+     * containing implementation of Java [annotation processor](https://jcp.org/en/jsr/detail?id=269).
+     *
+     * Configure this property with the same artifacts as its related [Kapt] task.
+     */
     @get:Internal("Not an input, just passed as kapt args. ")
     val kaptClasspath: ConfigurableFileCollection
 
+    /**
+     * @suppress
+     */
     @get:Deprecated(
         message = "Please migrate to compilerOptions.moduleName",
         replaceWith = ReplaceWith("compilerOptions.moduleName")
@@ -138,52 +216,102 @@ interface KaptGenerateStubs : KotlinJvmCompile {
     override val moduleName: Property<String>
 }
 
+/**
+ * Represents a Kotlin task that runs annotation processing using [Kotlin/Kapt](https://kotlinlang.org/docs/kapt.html).
+ *
+ * **Note:** Always run this task after its related [KaptGenerateStubs] and [KotlinJvmCompile] tasks.
+ */
 interface BaseKapt : Task,
     UsesKotlinJavaToolchain {
 
-    //part of kaptClasspath consisting from external artifacts only
-    //basically kaptClasspath = kaptExternalClasspath + artifacts built locally
+    // part of kaptClasspath consisting from external artifacts only
+    // basically kaptClasspath = kaptExternalClasspath + artifacts built locally
+    // TODO (Yahor): should not be a part of public api
+    /**
+     * @suppress
+     */
     @get:Classpath
     val kaptExternalClasspath: ConfigurableFileCollection
 
+    /**
+     * The names of Gradle's [org.gradle.api.artifacts.Configuration] that contains all the annotation processor artifacts
+     * used to configure [kaptClasspath].
+     */
     @get:Internal
     val kaptClasspathConfigurationNames: ListProperty<String>
 
     /**
-     * Output directory that contains caches necessary to support incremental annotation processing.
+     * The output directory containing the caches necessary to support incremental annotation processing.
      */
     @get:LocalState
     val incAptCache: DirectoryProperty
 
+    /**
+     * The directory where class files generated by annotation processing can be found.
+     */
     @get:OutputDirectory
     val classesDir: DirectoryProperty
 
+    /**
+     * The directory where Java source files generated by annotation processing can be found.
+     */
     @get:OutputDirectory
     val destinationDir: DirectoryProperty
 
-    /** Used in the model builder only. */
+    // Used in the model builder only
+    /**
+     * The directory where Java source files generated by annotation processing can be found.
+     */
     @get:OutputDirectory
     val kotlinSourcesDestinationDir: DirectoryProperty
 
+    /**
+     * Represents a list of annotation processor option providers.
+     *
+     * Accepts a [List] of [org.gradle.process.CommandLineArgumentProvider]s.
+     */
     @get:Nested
     val annotationProcessorOptionProviders: MutableList<Any>
 
+    /**
+     * The directory where the generated related [KaptGenerateStubs] task stub can be found.
+     */
     @get:Internal
     val stubsDir: DirectoryProperty
 
+    /**
+     * Allows adding artifacts (usually JAR files)
+     * that contain the implementation of the Java [annotation processor](https://jcp.org/en/jsr/detail?id=269).
+     *
+     * Should be configured with the same artifacts as in the related [KaptGenerateStubs] task.
+     */
     @get:Classpath
     val kaptClasspath: ConfigurableFileCollection
 
+    /**
+     * The directory that contains the compiled related [KotlinJvmCompile] task classes.
+     */
     @get:Internal
     val compiledSources: ConfigurableFileCollection
 
+    /**
+     * Contains all artifacts from the related [KotlinJvmCompile.libraries] task input.
+     */
     @get:Internal("Task implementation adds correct input annotation.")
     val classpath: ConfigurableFileCollection
 
-    /** Needed for the model builder. */
+    // Needed for the model builder
+    /**
+     * Specifies the name of [org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet] for which task is
+     * doing annotation processing.
+     */
     @get:Internal
     val sourceSetName: Property<String>
 
+    /**
+     * Contains all Java source code used in this compilation
+     * and generated by related [KaptGenerateStubs] task stubs.
+     */
     @get:InputFiles
     @get:IgnoreEmptyDirectories
     @get:Incremental
@@ -191,18 +319,45 @@ interface BaseKapt : Task,
     @get:PathSensitive(PathSensitivity.RELATIVE)
     val source: ConfigurableFileCollection
 
+    /**
+     * Enable searching for annotation processors in the [classpath].
+     */
     @get:Input
     val includeCompileClasspath: Property<Boolean>
 
+    /**
+     * Java source compatibility in the form of the Java language level for the produced class files and Java source code.
+     *
+     * Check the `javac` `-source` command line option
+     * [description](https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javac.html#options)
+     * for the possible values for the Java language level.
+     *
+     * @see [org.gradle.api.tasks.compile.AbstractCompile.setSourceCompatibility]
+     */
     @get:Internal("Used to compute javac option.")
     val defaultJavaSourceCompatibility: Property<String>
 }
 
+/**
+ * Represents a [BaseKapt] task whose implementation is running [Kotlin/Kapt](https://kotlinlang.org/docs/kapt.html)
+ * directly (without using the Kotlin compiler).
+ */
 interface Kapt : BaseKapt {
 
+    /**
+     * Add JDK classes to the [BaseKapt.classpath].
+     *
+     * For example, in Android projects this should be disabled.
+     */
     @get:Input
     val addJdkClassesToClasspath: Property<Boolean>
 
+    /**
+     * The file collection that contains `org.jetbrains.kotlin:kotlin-annotation-processing-gradle` and `kotlin-stdlib`
+     * artifacts that are used to run annotation processing.
+     *
+     * The artifacts' versions must be the same as the version of the Kotlin compiler used to compile the related Kotlin sources.
+     */
     @get:Classpath
     val kaptJars: ConfigurableFileCollection
 }

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

@@ -13,8 +13,8 @@ import org.jetbrains.kotlin.gradle.dsl.KotlinCommonCompilerToolOptions
 /**
  * Represents a Kotlin task performing further processing of compiled code via additional Kotlin tools using configurable [toolOptions].
  *
- * Check [KotlinCommonCompilerToolOptions] inheritors (excluding [KotlinCommonCompilerToolOptions]) for possible available for configuration
- * tool options.
+ * Check [KotlinCommonCompilerToolOptions] inheritors (excluding [KotlinCommonCompilerToolOptions]) for the possible configuration
+ * options.
  *
  * @see [KotlinCommonCompilerToolOptions]
  */