From 7c148e8d3b60d5bad8db4a7cadcfc783dcfca2f4 Mon Sep 17 00:00:00 2001
From: Bartek Pacia <barpac02@gmail.com>
Date: Wed, 23 Jul 2025 19:21:23 +0200
Subject: [PATCH] [devkit] IJPL-195964 Improve threadingModelHelper docs

GitOrigin-RevId: b1e14966cc4bc221c1b02272a1aac99236e96dfb
---
 .../threadingModelHelper/package-info.java    | 31 ++++++++-----------
 1 file changed, 13 insertions(+), 18 deletions(-)

diff --git a/plugins/devkit/jps-plugin/src/org/jetbrains/jps/devkit/threadingModelHelper/package-info.java b/plugins/devkit/jps-plugin/src/org/jetbrains/jps/devkit/threadingModelHelper/package-info.java
index 3ce43c7c1e8a..b51ea953dafe 100644
--- a/plugins/devkit/jps-plugin/src/org/jetbrains/jps/devkit/threadingModelHelper/package-info.java
+++ b/plugins/devkit/jps-plugin/src/org/jetbrains/jps/devkit/threadingModelHelper/package-info.java
@@ -3,31 +3,26 @@
 /**
  * <h2>Threading Model Helper</h2>
  * <p>
- * Instruments methods annotated with
+ * Instruments methods (including constructors) annotated with threading annotations by inserting a call to a corresponding assertion method.
+ * This call becomes the first instruction in the method's body.
  * <ul>
- * <li>{@code @RequiresEdt}
- * <li>{@code @RequiresBackgroundThread}
- * <li>{@code @RequiresReadLock}
- * <li>{@code @RequiresWriteLock}
- * <li>{@code @RequiresReadLockAbsence}
+ * <li>{@code @RequiresEdt} &rarr; {@code ThreadingAssertions.assertEventDispatchThread()}
+ * <li>{@code @RequiresBackgroundThread} &rarr; {@code ThreadingAssertions.assertBackgroundThread()}
+ * <li>{@code @RequiresReadLock} &rarr; {@code ThreadingAssertions.assertReadAccess()}
+ * <li>{@code @RequiresWriteLock} &rarr; {@code ThreadingAssertions.assertWriteAccess()}
+ * <li>{@code @RequiresReadLockAbsence} &rarr; {@code Application.assertNoReadAccess()}
  * </ul>
- * by inserting
- * <ul>
- * <li>{@code ThreadingAssertions.assertEventDispatchThread()}
- * <li>{@code Application.assertIsNonDispatchThread()}
- * <li>{@code Application.assertReadAccessAllowed()}
- * <li>{@code Application.assertWriteAccessAllowed()}
- * <li>{@code Application.assertReadAccessNotAllowed()}
- * </ul>
- * calls accordingly.
  * <p>
  * To disable the instrumentation, use the {@code tmh.generate.assertions.for.annotations} key in the Registry.
- *
  * <h3>Limitations</h3>
- *
  * <ul>
- * <li>Only Java code is instrumented,
+ * <li>Only Java code is instrumented.
  * <a href="https://youtrack.jetbrains.com/issue/IDEA-263465">Kotlin instrumentation is planned</a>.
+ * <li>Does not instrument parameters. Consider calling the corresponding assertion method manually.</li>
+ * <li>Does not instrument overriding methods. If the overriding method has the same threading contract as the supermethod,
+ * annotate it again.</li>
+ * <li>Does not instrument abstract methods, as there is no method body.</li>
  * </ul>
+ *
  */
 package org.jetbrains.jps.devkit.threadingModelHelper;
\ No newline at end of file