[Tests] Add javadoc for @TestMetadata

Merge-request: KT-MR-13338
Merged-by: Evgenii Mazhukin <evgenii.mazhukin@jetbrains.com>

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 {

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