chore: simplify comments

Signed-off-by: Akash Yadav <akashyadav@appdevforall.org>

Author: itsaky-adfa

build.gradle.kts

@@ -98,10 +98,9 @@ subprojects {
         //   - java.base/java.io, java.util: needed by Robolectric/Gradle worker
         //     reflection in the same test JVM.
         //   - java.base/java.util.concurrent: the embedded IntelliJ scheduler
-        //     (BoundedTaskExecutor.info -> AppDelayQueue "Periodic tasks thread")
-        //     reflectively reads FutureTask.callable. Without this the periodic
-        //     thread dies, disabling CoreProgressManager's cancellation poll that
-        //     makes the Kotlin Analysis API interruptible mid-`analyze`.
+        //     reflectively reads FutureTask.callable; without this its periodic
+        //     thread dies, disabling the cancellation poll that makes the Kotlin
+        //     Analysis API interruptible mid-`analyze`.
         jvmArgs(
             "--add-opens=java.base/java.lang=ALL-UNNAMED",
             "--add-opens=java.base/java.lang.reflect=ALL-UNNAMED",

editor/src/main/java/com/itsaky/androidide/editor/language/IDELanguage.kt

@@ -72,10 +72,9 @@ abstract class IDELanguage : Language {
 		try {
 			val cancelChecker = CompletionCancelChecker(publisher)
 			Lookup.getDefault().update(ICancelChecker::class.java, cancelChecker)
-			// Bind the checker to this completion thread. EditorCompletionWindow.cancelCompletion()
-			// cancels the (old) thread via ProgressManager.cancel(thread); routing that to *this*
-			// checker's cancel() lets the LSP's invokeOnCancel listener abort the running analysis
-			// mid-`analyze` immediately, instead of only at coarse checkpoints.
+			// Bind the checker to this thread so cancelCompletion()'s ProgressManager.cancel(thread)
+			// routes here, letting the LSP's invokeOnCancel abort the running analysis mid-`analyze`
+			// immediately rather than only at coarse checkpoints.
 			ProgressManager.instance.register(completionThread, cancelChecker)
 			doComplete(content, position, publisher, cancelChecker, extraArguments)
 		} finally {

editor/src/main/java/com/itsaky/androidide/editor/ui/EditorCompletionWindow.kt

@@ -51,11 +51,7 @@ class EditorCompletionWindow(val editor: IDEEditor) : EditorAutoCompletion(edito
 
         private val log = LoggerFactory.getLogger(EditorCompletionWindow::class.java)
 
-        /**
-         * Quiet period used to coalesce a burst of keystrokes into a single completion request. Rapid
-         * typing (re)schedules the start; only after the user pauses this long does one analysis run,
-         * for the latest cursor position. Keeps at most one completion in flight.
-         */
+        /** Quiet period for coalescing a keystroke burst: analysis runs only after typing pauses this long. */
         private const val COMPLETION_DEBOUNCE_MS = 80L
     }
 
@@ -141,10 +137,7 @@ class EditorCompletionWindow(val editor: IDEEditor) : EditorAutoCompletion(edito
         super.cancelCompletion()
     }
 
-    /**
-     * Whether a completion may be shown for the current editor state. Hides the window (matching the
-     * prior inline behaviour) when the cursor is selected or completion is otherwise not applicable.
-     */
+    /** Whether completion may run now; hides the window when the cursor is selected or otherwise not applicable. */
     private fun canStartCompletion(): Boolean {
         if (cancelShowUp || !isEnabled || !editor.isAttachedToWindow) {
             return false
@@ -156,29 +149,29 @@ class EditorCompletionWindow(val editor: IDEEditor) : EditorAutoCompletion(edito
         return true
     }
 
+    /**
+     * Coalesces a keystroke burst into one completion for the latest cursor position, keeping at most one
+     * analysis in flight. This prevents the CompletionThread/allocation pile-up that saturated the heap and
+     * froze the editor during fast typing.
+     */
     override fun requireCompletion() {
         if (!canStartCompletion()) {
             return
         }
 
-        // Coalesce a burst of keystrokes into a single completion. Cancel the in-flight completion and
-        // any pending (not-yet-started) one, then (re)schedule one start after a short quiet period.
-        // This guarantees at most one completion analysis in flight and that only the latest cursor
-        // position is computed — preventing the CompletionThread/allocation pile-up that saturated the
-        // heap and froze the editor during fast typing. cancelCompletion() clears any pending request,
-        // so we always schedule exactly one.
+        // cancelCompletion() clears any in-flight and pending request, so we then schedule exactly one.
         cancelCompletion()
 
         val request = Runnable { startCompletion() }
         pendingCompletion = request
         editor.handler.postDelayed(request, COMPLETION_DEBOUNCE_MS)
     }
 
-    /** Starts a single completion for the current cursor position. Runs on the UI thread. */
+    /** Runs on the UI thread. */
     private fun startCompletion() {
         pendingCompletion = null
 
-        // The editor state may have changed during the debounce delay; re-check the guards.
+        // Editor state may have changed during the debounce delay; re-check the guards.
         if (!canStartCompletion()) {
             return
         }

lsp/kotlin/src/main/java/com/itsaky/androidide/lsp/kotlin/compiler/CompilationEnvironment.kt

@@ -186,8 +186,7 @@ internal class CompilationEnvironment(
 					languageClient?.publishDiagnostics(result)
 				}
 			} catch (e: AnalysisPreemptedException) {
-				// A higher-priority analysis (completion) preempted this diagnostics run.
-				// Re-schedule so diagnostics still run once the higher-priority work finishes.
+				// Preempted by completion; re-schedule so diagnostics still run once it finishes.
 				logger.debug("diagnostics for {} preempted; rescheduling", path)
 				fileAnalyzer.schedule(path)
 			}

lsp/kotlin/src/main/java/com/itsaky/androidide/lsp/kotlin/compiler/index/SourceFileIndexer.kt

@@ -76,10 +76,9 @@ internal suspend fun indexSourceFile(
 	symbolsIndex: JvmSymbolIndex,
 	cancelChecker: ICancelChecker,
 ) {
-	// Indexing runs at the lowest (INDEXING) priority: it yields to both completion and diagnostics.
-	// Wrapping the checker lets the scheduler preempt an in-progress index pass; the preemption
-	// surfaces as AnalysisPreemptedException at the abortIfCancelled() checkpoints below, which the
-	// IndexWorker catches to re-queue the file.
+	// Indexing runs at the lowest priority, yielding to completion and diagnostics. Wrapping the checker
+	// lets the scheduler preempt an in-progress pass; the preemption surfaces as AnalysisPreemptedException
+	// at the abortIfCancelled() checkpoints below, which IndexWorker catches to re-queue the file.
 	val checker = cancelChecker as? ScheduledCancelChecker ?: ScheduledCancelChecker(cancelChecker)
 
 	// Defensive backstop: this runs on the debounced/async index scope, so a disposal path that

lsp/kotlin/src/main/java/com/itsaky/androidide/lsp/kotlin/compiler/modules/AnalysisScheduler.kt

@@ -15,14 +15,11 @@ import kotlin.concurrent.withLock
  * Order: [INDEXING] < [DIAGNOSTICS] < [COMPLETION] — interactive completion beats background
  * diagnostics, which beats bulk indexing.
  *
- * [supersedesSamePriority] additionally lets a *newer* request preempt an in-flight request of the
- * **same** priority. This is enabled only for [COMPLETION]: when the user types fast, several
- * completion requests fire in a row and the in-flight one is computing results for a now-stale cursor
- * position, so the newer request cancels it and the fresh position is analysed immediately. A
- * superseded completion is simply *discarded* — nothing reschedules it (see
- * `KotlinCompletions.codeComplete`). It is intentionally off for [DIAGNOSTICS] and [INDEXING], whose
- * preempted work is re-queued rather than dropped; same-priority preemption there would livelock, as
- * two contenders would endlessly re-queue and re-preempt each other.
+ * [supersedesSamePriority] additionally lets a *newer* request preempt an in-flight one of the
+ * **same** priority. On for [COMPLETION] only: rapid typing makes the in-flight completion stale, so
+ * the newer one cancels it and the superseded work is *discarded* (nothing reschedules it). Off for
+ * [DIAGNOSTICS]/[INDEXING], whose preempted work is re-queued — there same-priority preemption would
+ * livelock, two contenders endlessly re-queuing and re-preempting each other.
  */
 internal enum class AnalysisPriority(val supersedesSamePriority: Boolean) {
 	INDEXING(supersedesSamePriority = false),
@@ -62,7 +59,7 @@ internal class ScheduledCancelChecker(
 	/** Marks this analysis as preempted; the next [abortIfCancelled] will throw. */
 	fun preempt() {
 		preempted = true
-		// Push: preemption is a cancellation too, so notify [invokeOnCancel] listeners immediately.
+		// Preemption is a cancellation too: fire invokeOnCancel listeners now, don't wait for a poll.
 		onCancelListeners.forEach { it() }
 		onCancelListeners.clear()
 	}
@@ -131,11 +128,10 @@ internal object AnalysisScheduler {
 	 * priority is [AnalysisPriority.supersedesSamePriority] — [onPreempt] of *that* holder is invoked so
 	 * it yields; [onPreempt] passed here is stored and used if this acquisition is later preempted.
 	 *
-	 * [cancelChecker] is *this* requester's checker: while waiting for the lock, the wait is re-checked on
-	 * a short timer, and if the requester has been cancelled — e.g. the editor superseded
-	 * this completion — [acquire] throws instead of parking until the lock frees. This is what stops
-	 * superseded completions from piling up holding heavy state (KtFile copies, symbol lists) while they
-	 * wait, which on-device saturated the heap and triggered multi-second GC stalls.
+	 * [cancelChecker] is *this* requester's checker: a queued requester re-checks it on a short timer and
+	 * [acquire] throws (rather than park until the lock frees) once cancelled — e.g. the editor superseded
+	 * this completion. This stops superseded completions from piling up holding heavy state (KtFile copies,
+	 * symbol lists), which on-device saturated the heap and triggered multi-second GC stalls.
 	 */
 	fun acquire(priority: AnalysisPriority, cancelChecker: ICancelChecker, onPreempt: () -> Unit) {
 		mutex.withLock {

lsp/kotlin/src/main/java/com/itsaky/androidide/lsp/kotlin/compiler/modules/AnalysisThreadContext.java

@@ -6,17 +6,11 @@
 import org.jetbrains.kotlin.com.intellij.openapi.application.AccessToken;
 
 /**
- * Bridge to the embeddable IntelliJ {@link ThreadContext} coroutine-context API.
+ * Java bridge to the embeddable IntelliJ {@link ThreadContext} coroutine-context API.
  *
- * <p>{@code currentThreadContext}/{@code installThreadContext} live in a Kotlin file facade whose
- * metadata the Kotlin compiler cannot resolve against from this module (they surface as
- * "unresolved reference" from Kotlin). At the bytecode level, though, they are plain
- * {@code public static} methods, so Java can call them directly.
- *
- * <p>This is used by {@code withAnalysisLock} to install a cancellable {@link Job} into the analysis
- * thread's context: the embeddable {@code CoreProgressManager.checkCanceled()} routes through
- * {@code Cancellation.checkCancelled()}, which throws as soon as that Job is cancelled, aborting the
- * running analysis mid-{@code analyze}.
+ * <p>Exists in Java because {@code currentThreadContext}/{@code installThreadContext} live in a
+ * Kotlin file-facade whose metadata this module's Kotlin compiler cannot resolve ("unresolved
+ * reference"), yet at the bytecode level they are plain {@code public static} methods Java can call.
  */
 public final class AnalysisThreadContext {
 
@@ -25,10 +19,12 @@ private AnalysisThreadContext() {
 
   /**
    * Installs {@code job} into the current thread's IntelliJ coroutine context (preserving any
-   * context already present) and returns a token that restores the previous context when closed.
+   * existing context) and returns a token that restores the previous context when closed. Cancelling
+   * {@code job} then aborts the running analysis mid-{@code analyze}, since the embeddable
+   * {@code CoreProgressManager.checkCanceled()} throws once the installed Job is cancelled.
    *
-   * <p>Public because it is referenced from the {@code internal inline} {@code withAnalysisLock};
-   * an inline function may only reference declarations at least as accessible as itself.
+   * <p>Public (not package-private) because the {@code internal inline} {@code withAnalysisLock}
+   * references it: an inline function may only reference declarations at least as accessible as itself.
    */
   public static AccessToken installJob(Job job) {
     CoroutineContext context = ThreadContext.currentThreadContext().plus(job);

lsp/kotlin/src/main/java/com/itsaky/androidide/lsp/kotlin/compiler/modules/CancelCheckerProgressIndicator.kt

@@ -5,22 +5,15 @@ import org.jetbrains.kotlin.com.intellij.openapi.progress.ProcessCanceledExcepti
 import org.jetbrains.kotlin.com.intellij.openapi.progress.util.AbstractProgressIndicatorBase
 
 /**
- * A [com.intellij.openapi.progress.ProgressIndicator] whose cancellation state is driven by an
- * [ICancelChecker]. Installing it as the analysis thread's indicator (via
- * [withAnalysisLock]) is what makes the Kotlin Analysis API actually interruptible *mid*-`analyze`.
+ * A progress indicator whose cancellation is driven by an [ICancelChecker]. Installing it as the
+ * analysis thread's indicator (via [withAnalysisLock]) makes the Kotlin Analysis API interruptible
+ * *mid*-`analyze`: the embeddable `CoreProgressManager.checkCanceled()` (called densely throughout
+ * FIR resolution) rethrows this indicator's [checkCanceled], so a preemption or cancellation aborts
+ * at the compiler's next internal checkpoint, not only at the coarse [ICancelChecker.abortIfCancelled].
  *
- * The embeddable analysis API ships the full IntelliJ `CoreProgressManager`, whose
- * `ProgressManager.checkCanceled()` (called densely throughout FIR resolution) re-fetches the
- * current thread's indicator and rethrows its [checkCanceled]. By bridging that to [checker], a
- * preemption or ordinary cancellation aborts the running analysis at the compiler's next internal
- * checkpoint instead of only at the coarse LSP-level [ICancelChecker.abortIfCancelled] checks.
- *
- * This extends [AbstractProgressIndicatorBase] rather than `EmptyProgressIndicator` on purpose:
- * the base is a *non-standard* indicator, so `CoreProgressManager` runs a background task that
- * polls [checkCanceled] every ~10ms. That poll flips the manager's internal "should check
- * cancelled" flag to active once [checker] reports cancellation, which is what arms the in-`analyze`
- * checks. [cancel] (invoked synchronously when this analysis is preempted) flips the same flag
- * immediately, so preemption does not have to wait for the poll.
+ * Extends [AbstractProgressIndicatorBase] (a *non-standard* indicator) on purpose: `CoreProgressManager`
+ * then polls [checkCanceled] every ~10ms, arming its internal "check cancelled" flag once [checker]
+ * reports cancellation. `cancel()` flips that flag immediately so preemption need not wait for the poll.
  */
 internal class CancelCheckerProgressIndicator(
 	private val checker: ICancelChecker,