diff --git a/platform/ide-core/src/com/intellij/util/SingleAlarm.kt b/platform/ide-core/src/com/intellij/util/SingleAlarm.kt
index a33d4bcad252..80ef380affdb 100644
--- a/platform/ide-core/src/com/intellij/util/SingleAlarm.kt
+++ b/platform/ide-core/src/com/intellij/util/SingleAlarm.kt
@@ -10,6 +10,14 @@ import java.util.concurrent.ExecutionException
 import java.util.concurrent.TimeUnit
 import java.util.concurrent.TimeoutException
 
+/**
+ * Allows scheduling a single `Runnable` instance ([task]) to be executed after a specific time interval on a specific thread.
+ * [request] adds a request if it's not scheduled yet, i.e., it does not delay execution of the request
+ * [cancelAndRequest] cancels the current request and schedules a new one instead, i.e., it delays execution of the request
+ *
+ * Consider using a [kotlinx.coroutines.flow.Flow] with [kotlinx.coroutines.flow.debounce] and [kotlinx.coroutines.flow.sample] instead
+ */
+
 class SingleAlarm @JvmOverloads constructor(
   private val task: Runnable,
   private val delay: Int,