From 5cd159ec4b6f7e51826240172972512a2bd9b243 Mon Sep 17 00:00:00 2001
From: Konstantin Nisht <konstantin.nisht@jetbrains.com>
Date: Thu, 21 Mar 2024 18:38:39 +0100
Subject: [PATCH] [platform] Fix docs

GitOrigin-RevId: 37637565c5fb07930f7b0e4c43e6bf2021afa293
---
 .../platform/backend/observation/Observation.kt       | 11 ++++++++++-
 .../observation/PlatformActivityTrackerService.kt     |  8 ++++++--
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/platform/backend/observation/src/com/intellij/platform/backend/observation/Observation.kt b/platform/backend/observation/src/com/intellij/platform/backend/observation/Observation.kt
index fcfd3daf69c3..fa3676095da7 100644
--- a/platform/backend/observation/src/com/intellij/platform/backend/observation/Observation.kt
+++ b/platform/backend/observation/src/com/intellij/platform/backend/observation/Observation.kt
@@ -7,7 +7,16 @@ import kotlinx.coroutines.flow.StateFlow
 object Observation {
 
   /**
-   * Returns the flow representing ongoing configuration processes in a project.
+   * A flow that represents a state of configuration processes in a project.
+   * Configuration process is a generic name for indexing, build system import, VFS refresh, or similar CPU-heavy activity
+   * that change the readiness of the project.
+   *
+   * It is discouraged to perform project modification in collectors of this flow,
+   * since project modifications should be *covered* by the tracking machinery, which is the core principle behind this flow.
+   *
+   * The values in the flow may "blink", in the sense that every VFS refresh may trigger the change of states in the flow.
+   * One is advised to use [kotlinx.coroutines.flow.debounce] or similar operations to obtain proper granularity.
+   *
    * @return a state flow containing `true` if the configuration process is currently running,
    * or `false` otherwise.
    */
diff --git a/platform/backend/observation/src/com/intellij/platform/backend/observation/PlatformActivityTrackerService.kt b/platform/backend/observation/src/com/intellij/platform/backend/observation/PlatformActivityTrackerService.kt
index 6f3b3c502c7d..c9c7eb072944 100644
--- a/platform/backend/observation/src/com/intellij/platform/backend/observation/PlatformActivityTrackerService.kt
+++ b/platform/backend/observation/src/com/intellij/platform/backend/observation/PlatformActivityTrackerService.kt
@@ -120,7 +120,11 @@ internal class PlatformActivityTrackerService(private val scope: CoroutineScope)
     val counter = flowCounter.getAndIncrement()
     if (counter == 0) {
       while (!ongoingConfigurationFlow.compareAndSet(false, true)) {
-        // The loop can spin only if the activity finishes very fast and
+        // The loop should not spin for long.
+        // Suppose we have two activities: the first one is fast, and the second one is slow.
+        // CAS may fail only if slow activity sets itself before the fast one,
+        // but in this case the ending of the fast activity would set `false` back, and fast activity would be able to set `true` again.
+        // This can cause a blink, but it is technically correct.
       }
     }
   }
@@ -155,7 +159,7 @@ internal class PlatformActivityTrackerService(private val scope: CoroutineScope)
     val counter = flowCounter.decrementAndGet()
     if (counter == 0) {
       while (!ongoingConfigurationFlow.compareAndSet(true, false)) {
-        // The loop can spin only if the activity finishes very fast and
+        // See the comment in a similar loop of `enterConfiguration`
       }
     }
   }