diff --git a/java/testFramework/shared/src/com/intellij/testFramework/IdeaTestUtil.java b/java/testFramework/shared/src/com/intellij/testFramework/IdeaTestUtil.java
index 0459123d4b38..70cf60b7b1ab 100644
--- a/java/testFramework/shared/src/com/intellij/testFramework/IdeaTestUtil.java
+++ b/java/testFramework/shared/src/com/intellij/testFramework/IdeaTestUtil.java
@@ -114,6 +114,40 @@ public final class IdeaTestUtil {
     return getMockJdk(level.toJavaVersion());
   }
 
+  /**
+   * Returns a mock JDK for the specified Java version.
+   *
+   * <h3>Version Mapping</h3>
+   * Mock JDKs are simplified JDKs with limited class coverage. The requested version
+   * is mapped to the nearest available mock JDK:
+   * <ul>
+   *   <li>Java 4-6 → Mock JDK 1.7</li>
+   *   <li>Java 7 → Mock JDK 1.7</li>
+   *   <li>Java 8 → Mock JDK 1.8</li>
+   *   <li>Java 9-10 → Mock JDK 9</li>
+   *   <li>Java 11-20 → Mock JDK 11</li>
+   *   <li>Java 21-24 → Mock JDK 21</li>
+   *   <li>Java 25+ → Mock JDK 25</li>
+   * </ul>
+   *
+   * <h3>Class Coverage</h3>
+   * <table border="1">
+   *   <caption>Mock JDK Class Coverage</caption>
+   *   <tr><th>Mock JDK</th><th>java.io.File</th><th>java.nio.file.*</th><th>Source</th></tr>
+   *   <tr><td>1.7</td><td>Yes</td><td>No</td><td>community/java/mockJDK-1.7/</td></tr>
+   *   <tr><td>1.8</td><td>Yes</td><td>No</td><td>community/java/mockJDK-1.8/</td></tr>
+   *   <tr><td>11+</td><td>Yes</td><td>Yes</td><td>Maven: org.jetbrains.mockjdk:mockjdk-base-java</td></tr>
+   * </table>
+   *
+   * <h3>Common Pitfall</h3>
+   * If your test uses {@code java.nio.file.Path} (e.g., {@code File.toPath()}),
+   * you need Mock JDK 11 or higher. Use {@link #getMockJdk11()} or specify
+   * {@code JavaVersion.compose(11)} or higher.
+   *
+   * @param version the desired Java version
+   * @return a mock JDK SDK
+   * @see #getMockJdk11()
+   */
   public static @NotNull Sdk getMockJdk(@NotNull JavaVersion version) {
     int mockJdk = version.feature >= 25 ? 25 :
                   version.feature >= 21 ? 21 :
@@ -228,39 +262,107 @@ public final class IdeaTestUtil {
     return createMockJdk(name, path, null);
   }
 
-  /// It's JDK 1.4, not 14.
+  /**
+   * Returns Mock JDK 1.4 (Java 4).
+   *
+   * <p><b>Warning:</b> The method name "14" refers to version "1.4" (Java 4), NOT Java 14.
+   *
+   * @return Mock JDK 1.4 (Java 4)
+   * @see #getMockJdk(JavaVersion) for version mapping and class coverage details
+   */
   public static @NotNull Sdk getMockJdk14() {
     return getMockJdk(JavaVersion.compose(4));
   }
 
-  /// It's JDK 1.6, not 16.
+  /**
+   * Returns Mock JDK 1.7 (Java 7), since there is no Mock JDK 1.6.
+   *
+   * <p><b>Warning:</b> The method name "16" refers to version "1.6" (Java 6), NOT Java 16.
+   * This actually returns Mock JDK 1.7 due to version mapping.
+   *
+   * @return Mock JDK 1.7 (Java 7)
+   * @see #getMockJdk(JavaVersion) for version mapping and class coverage details
+   */
   public static @NotNull Sdk getMockJdk16() {
     return getMockJdk(JavaVersion.compose(6));
   }
 
-  /// It's JDK 1.7, not 17.
+  /**
+   * Returns Mock JDK 1.7 (Java 7).
+   *
+   * <p><b>Warning:</b> The method name "17" refers to version "1.7" (Java 7), NOT Java 17.
+   * For Java 17, use {@code getMockJdk(JavaVersion.compose(17))}.
+   *
+   * <p>This mock JDK does NOT contain {@code java.nio.file.*} classes.
+   * If you need {@code Path}, {@code Paths}, or {@code Files}, use {@link #getMockJdk11()}.
+   *
+   * @return Mock JDK 1.7 (Java 7)
+   * @see #getMockJdk11() for tests needing java.nio.file.*
+   * @see #getMockJdk(JavaVersion) for version mapping and class coverage details
+   */
   public static @NotNull Sdk getMockJdk17() {
     return getMockJdk(JavaVersion.compose(7));
   }
 
-  /// It's JDK 1.7, not 17.
+  /**
+   * Returns Mock JDK 1.7 (Java 7) with a custom name.
+   *
+   * <p><b>Warning:</b> The method name "17" refers to version "1.7" (Java 7), NOT Java 17.
+   *
+   * @param name the SDK name
+   * @return Mock JDK 1.7 (Java 7)
+   * @see #getMockJdk17()
+   */
   public static @NotNull Sdk getMockJdk17(@NotNull String name) {
     return createMockJdk(name, getMockJdk17Path().getPath());
   }
 
-  /// It's JDK 1.8, not 18.
+  /**
+   * Returns Mock JDK 1.8 (Java 8).
+   *
+   * <p><b>Warning:</b> The method name "18" refers to version "1.8" (Java 8), NOT Java 18.
+   * For Java 18, use {@code getMockJdk(JavaVersion.compose(18))}.
+   *
+   * <p>This mock JDK does NOT contain {@code java.nio.file.*} classes.
+   * If you need {@code Path}, {@code Paths}, or {@code Files}, use {@link #getMockJdk11()}.
+   *
+   * @return Mock JDK 1.8 (Java 8)
+   * @see #getMockJdk11() for tests needing java.nio.file.*
+   * @see #getMockJdk(JavaVersion) for version mapping and class coverage details
+   */
   public static @NotNull Sdk getMockJdk18() {
     return getMockJdk(JavaVersion.compose(8));
   }
 
+  /**
+   * Returns Mock JDK 9.
+   *
+   * @return Mock JDK 9
+   * @see #getMockJdk(JavaVersion) for version mapping and class coverage details
+   */
   public static @NotNull Sdk getMockJdk9() {
     return getMockJdk(JavaVersion.compose(9));
   }
-  
+
+  /**
+   * Returns Mock JDK 11.
+   *
+   * <p>This is the recommended mock JDK for tests that need {@code java.nio.file.*} classes
+   * ({@code Path}, {@code Paths}, {@code Files}). Mock JDKs 1.7 and 1.8 do NOT contain these classes.
+   *
+   * @return Mock JDK 11
+   * @see #getMockJdk(JavaVersion) for version mapping and class coverage details
+   */
   public static @NotNull Sdk getMockJdk11() {
     return getMockJdk(JavaVersion.compose(11));
   }
 
+  /**
+   * Returns Mock JDK 21.
+   *
+   * @return Mock JDK 21
+   * @see #getMockJdk(JavaVersion) for version mapping and class coverage details
+   */
   public static @NotNull Sdk getMockJdk21() {
     return getMockJdk(JavaVersion.compose(21));
   }
diff --git a/java/testFramework/src/com/intellij/testFramework/fixtures/DefaultLightProjectDescriptor.java b/java/testFramework/src/com/intellij/testFramework/fixtures/DefaultLightProjectDescriptor.java
index 4c08f2919193..d5b5c591d116 100644
--- a/java/testFramework/src/com/intellij/testFramework/fixtures/DefaultLightProjectDescriptor.java
+++ b/java/testFramework/src/com/intellij/testFramework/fixtures/DefaultLightProjectDescriptor.java
@@ -43,6 +43,22 @@ public class DefaultLightProjectDescriptor extends LightProjectDescriptor {
     return JAVA_MODULE_ENTITY_TYPE_ID_NAME;
   }
 
+  /**
+   * Returns the SDK for tests using this descriptor.
+   *
+   * <p><b>Default:</b> Returns {@link IdeaTestUtil#getMockJdk17()} (Mock JDK 1.7, Java 7).
+   *
+   * <p><b>Important:</b> Mock JDK 1.7 does NOT contain {@code java.nio.file.*} classes.
+   * If your test needs {@code Path}, {@code Paths}, or {@code Files}, create a custom
+   * descriptor with a higher JDK version:
+   * <pre>{@code
+   * private static final LightProjectDescriptor DESCRIPTOR =
+   *     new DefaultLightProjectDescriptor(IdeaTestUtil::getMockJdk11);
+   * }</pre>
+   *
+   * @return the SDK, defaults to Mock JDK 1.7 (Java 7)
+   * @see IdeaTestUtil#getMockJdk(com.intellij.util.lang.JavaVersion) for version mapping details
+   */
   @Override
   public Sdk getSdk() {
     return customSdk == null ? IdeaTestUtil.getMockJdk17() : customSdk.get();
diff --git a/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase.java b/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase.java
index c1166acb3456..68f77d29bb4f 100644
--- a/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase.java
+++ b/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase.java
@@ -29,6 +29,28 @@ import java.io.File;
  *   <li>Creates a simpler in-memory project structure</li>
  *   <li>Faster to initialize and run but with some limitations</li>
  * </ul>
+ *
+ * <h3>Predefined Project Descriptors and Mock JDK Coverage</h3>
+ * <table border="1">
+ *   <caption>Project Descriptors with Mock JDK Versions and Class Coverage</caption>
+ *   <tr><th>Descriptor</th><th>Language Level</th><th>Mock JDK</th><th>java.nio.file.*</th></tr>
+ *   <tr><td>{@link #JAVA_1_7}</td><td>JDK_1_7</td><td>1.7</td><td>No</td></tr>
+ *   <tr><td>{@link #JAVA_8}</td><td>JDK_1_8</td><td>1.8</td><td>No</td></tr>
+ *   <tr><td>{@link #JAVA_11}</td><td>JDK_11</td><td>11</td><td>Yes</td></tr>
+ *   <tr><td>{@link #JAVA_17}</td><td>JDK_17</td><td>11 (mapped)</td><td>Yes</td></tr>
+ *   <tr><td>{@link #JAVA_21}</td><td>JDK_21</td><td>21</td><td>Yes</td></tr>
+ *   <tr><td>{@link #JAVA_LATEST}</td><td>HIGHEST</td><td><b>1.7!</b></td><td>No</td></tr>
+ *   <tr><td>{@link #JAVA_LATEST_WITH_LATEST_JDK}</td><td>HIGHEST</td><td>matches level</td><td>Yes</td></tr>
+ * </table>
+ *
+ * <p><b>Warning:</b> {@link #JAVA_LATEST} uses Mock JDK 1.7 despite having the highest
+ * language level. If you need modern JDK classes like {@code java.nio.file.Path},
+ * use {@link #JAVA_LATEST_WITH_LATEST_JDK} or {@link #JAVA_11} instead.
+ *
+ * <p>The {@code _ANNOTATED} variants (e.g., {@link #JAVA_11_ANNOTATED}) include JDK annotations
+ * for nullability and other contracts.
+ *
+ * @see IdeaTestUtil#getMockJdk(com.intellij.util.lang.JavaVersion) for mock JDK version mapping details
  * @see LightJavaCodeInsightFixtureTestCase4
  * @see LightJavaCodeInsightFixtureTestCase5
  */
@@ -90,7 +112,13 @@ public abstract class LightJavaCodeInsightFixtureTestCase extends UsefulTestCase
   public static final @NotNull LightProjectDescriptor JAVA_8_ANNOTATED = new ProjectDescriptor(LanguageLevel.JDK_1_8, true);
   public static final @NotNull LightProjectDescriptor JAVA_9 = new ProjectDescriptor(LanguageLevel.JDK_1_9);
   public static final @NotNull LightProjectDescriptor JAVA_9_ANNOTATED = new ProjectDescriptor(LanguageLevel.JDK_1_9, true);
+  /**
+   * Project descriptor with Java 11 language level and Mock JDK 11.
+   * <p>Use this when your test needs {@code java.nio.file.*} classes
+   * ({@code Path}, {@code Paths}, {@code Files}). Mock JDKs 1.7 and 1.8 do NOT contain these classes.
+   */
   public static final @NotNull LightProjectDescriptor JAVA_11 = new ProjectDescriptor(LanguageLevel.JDK_11);
+  /** Project descriptor with Java 11 and JDK annotations for nullability contracts. */
   public static final @NotNull LightProjectDescriptor JAVA_11_ANNOTATED = new ProjectDescriptor(LanguageLevel.JDK_11, true);
   public static final @NotNull LightProjectDescriptor JAVA_12 = new ProjectDescriptor(LanguageLevel.JDK_12);
   public static final @NotNull LightProjectDescriptor JAVA_13 = new ProjectDescriptor(LanguageLevel.JDK_13);
@@ -110,13 +138,28 @@ public abstract class LightJavaCodeInsightFixtureTestCase extends UsefulTestCase
   public static final @NotNull LightProjectDescriptor JAVA_25 = new ProjectDescriptor(LanguageLevel.JDK_25);
   public static final @NotNull LightProjectDescriptor JAVA_X = new ProjectDescriptor(LanguageLevel.JDK_X);
 
+  /**
+   * Project descriptor with highest language level but <b>Mock JDK 1.7 (Java 7)</b>.
+   * <p><b>Warning:</b> Despite the name, this uses Java 7 mock JDK which does NOT
+   * contain {@code java.nio.file.*} classes ({@code Path}, {@code Paths}, {@code Files}).
+   * If you need those classes, use {@link #JAVA_LATEST_WITH_LATEST_JDK} or {@link #JAVA_11} instead.
+   *
+   * @see #JAVA_LATEST_WITH_LATEST_JDK for descriptor with matching mock JDK
+   * @see #JAVA_11 for tests needing java.nio.file.* classes
+   */
   public static final @NotNull LightProjectDescriptor JAVA_LATEST = new ProjectDescriptor(LanguageLevel.HIGHEST) {
     @Override
     public Sdk getSdk() {
       return IdeaTestUtil.getMockJdk17();
     }
   };
-  
+
+  /**
+   * Project descriptor with highest language level AND matching mock JDK.
+   * <p>Unlike {@link #JAVA_LATEST}, this descriptor uses a mock JDK that matches
+   * the language level, so {@code java.nio.file.*} classes ({@code Path}, {@code Paths}, {@code Files})
+   * are available.
+   */
   public static final @NotNull LightProjectDescriptor JAVA_LATEST_WITH_LATEST_JDK = new ProjectDescriptor(LanguageLevel.HIGHEST);
 
   protected JavaCodeInsightTestFixture myFixture;