[platform] Fix docs

GitOrigin-RevId: 37637565c5fb07930f7b0e4c43e6bf2021afa293

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.
    */

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`
       }
     }
   }