[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 {