From 834602b7370f57f59380918b0a4f1a62de7add14 Mon Sep 17 00:00:00 2001
From: Evgenii Mazhukin <evgenii.mazhukin@jetbrains.com>
Date: Mon, 4 Dec 2023 17:29:42 +0000
Subject: [PATCH] [Tests] Add javadoc for @TestMetadata

Merge-request: KT-MR-13338
Merged-by: Evgenii Mazhukin <evgenii.mazhukin@jetbrains.com>
---
 .../org/jetbrains/kotlin/test/TestMetadata.java    | 14 ++++++++++++++
 .../testbase/kotlinSourceFileTransformations.kt    | 10 ++++++++++
 2 files changed, 24 insertions(+)

diff --git a/compiler/test-infrastructure-utils/tests/org/jetbrains/kotlin/test/TestMetadata.java b/compiler/test-infrastructure-utils/tests/org/jetbrains/kotlin/test/TestMetadata.java
index 6cbfee575f7..c6358b2eff0 100644
--- a/compiler/test-infrastructure-utils/tests/org/jetbrains/kotlin/test/TestMetadata.java
+++ b/compiler/test-infrastructure-utils/tests/org/jetbrains/kotlin/test/TestMetadata.java
@@ -21,6 +21,20 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Used by DevKit IDE Plugin to find "related testData".
+ * Plugin provides various IDE-assistance (e.g. "NavigateToTestData"-actions and gutter icons).
+ *
+ * The main annotation is @[com.intellij.testFramework.TestDataPath].
+ * @[TestDataPath] is usually set on the base class, and @[TestMetadata] - on test methods.
+ * Without @[TestMetadata], a path based on test name is computed:
+ *
+ * <table summary="">
+ * <tr> <th>Lookup rule</th>            <th>Test name</th>  <th>Related testData path</th> </tr>
+ * <tr> <td>default</td>                <td>testFoo</td>    <td>'{argument-of-@TestDataPath}/foo'</td> </tr>
+ * <tr> <td>with @[TestMetadata]</td>   <td>testFoo</td>    <td>'{argument-of-@TestDataPath}/{argument-of-@TestMetadata}'</td> </tr>
+ * </table>
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.METHOD, ElementType.TYPE})
 public @interface TestMetadata {
diff --git a/libraries/tools/kotlin-gradle-plugin-integration-tests/src/test/kotlin/org/jetbrains/kotlin/gradle/testbase/kotlinSourceFileTransformations.kt b/libraries/tools/kotlin-gradle-plugin-integration-tests/src/test/kotlin/org/jetbrains/kotlin/gradle/testbase/kotlinSourceFileTransformations.kt
index c2de489b54c..bd707c07f21 100644
--- a/libraries/tools/kotlin-gradle-plugin-integration-tests/src/test/kotlin/org/jetbrains/kotlin/gradle/testbase/kotlinSourceFileTransformations.kt
+++ b/libraries/tools/kotlin-gradle-plugin-integration-tests/src/test/kotlin/org/jetbrains/kotlin/gradle/testbase/kotlinSourceFileTransformations.kt
@@ -11,11 +11,21 @@ import java.util.concurrent.atomic.AtomicInteger
 import kotlin.io.path.appendText
 
 
+/**
+ * Appends top-level `private val` to the content of the file.
+ * Throws SecurityException or IOException, if append failed.
+ * Every call to [addPrivateVal] or [addPublicVal] generates a new value name.
+ */
 fun Path.addPrivateVal(): Path {
     appendText("\nprivate val integerValue${changeCounter.incrementAndGet()} = 24\n")
     return this
 }
 
+/**
+ * Appends top-level `public val` to the content of the file.
+ * Throws SecurityException or IOException, if append failed.
+ * Every call to [addPrivateVal] or [addPublicVal] generates a new value name.
+ */
 fun Path.addPublicVal(): Path {
     appendText("\nval integerValue${changeCounter.incrementAndGet()} = 25\n")
     return this