improve comments

apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/model/ChatModel.kt

@@ -45,9 +45,8 @@ import kotlin.collections.ArrayList
 import kotlin.random.Random
 import kotlin.time.*
 
-// A directory search and a connection can overlap - tapping a result starts a connection while
-// the search is still running - so the single progress slot records its owner: a late search
-// result must not clear the spinner that now belongs to the connection.
+// There is one spinner, and a search and a connection can run at once - tapping a result starts
+// connecting while the search is still going - so it records which of them it belongs to.
 enum class ConnectProgressOwner { Connect, DirectorySearch }
 
 object ConnectProgressManager {
@@ -68,6 +67,7 @@ object ConnectProgressManager {
     }
   }
 
+  // a search finishing late must not stop the spinner if a connection has taken it over
   fun stopConnectProgress(owner: ConnectProgressOwner = ConnectProgressOwner.Connect) {
     if (this.owner != null && this.owner != owner) return
     connectInProgress.value = null
@@ -76,7 +76,7 @@ object ConnectProgressManager {
     connectProgressByTimeout.value = false
   }
 
-  // a user-initiated cancel, and the takeover in planAndConnect, cancel whatever is running
+  // unlike stopConnectProgress, this cancels whoever owns the spinner
   fun cancelConnectProgress() {
     val cancel = onCancel
     owner = null

apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/model/DirectorySearch.kt

@@ -4,13 +4,11 @@ import kotlinx.datetime.Instant
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.json.*
 
-// The directory's contact address, as published in docs/DIRECTORY.md. It must be the short
-// link: only that form carries the address DR keys that service requests require, so the full
-// links on the What's New cards cannot be substituted here.
+// The directory's address, as published in docs/DIRECTORY.md. It must be the short link form -
+// only that one carries the keys a service request needs; a full link fails every time.
 const val DIRECTORY_SERVICE_LINK = "https://smp4.simplex.im/a#lXUjJW5vHYQzoLYgmi8GbxkGP41_kjefFvBrdwg-0Ok"
 
-// A service request is a full DR handshake, so it is slower than a local API call; the user
-// gets a cancellable spinner while it runs and a retry row if it times out.
+// A search sets up an encrypted connection, so it takes seconds, not milliseconds.
 const val DIRECTORY_SEARCH_TIMEOUT_SEC = 10.0
 
 @Serializable
@@ -52,8 +50,8 @@ fun directorySearchRequest(text: String, cursor: JsonObject?): JsonObject = buil
   if (cursor != null) put("searchCursor", cursor)
 }
 
-// The response is a tagged object: searchResults or error. Anything else is treated as a failure
-// rather than parsed leniently - it comes from outside the app.
+// Anything but a well-formed results response is a failure, not something to salvage: it comes
+// from another party, not from our own core.
 fun parseDirectorySearchResponse(resp: JsonObject): DirectorySearchResults? =
   when ((resp["type"] as? JsonPrimitive)?.contentOrNull) {
     "searchResults" -> {

apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/model/SimpleXAPI.kt

@@ -1630,9 +1630,8 @@ object ChatController {
     return null
   }
 
-  // Blocks until the directory replies or the timeout elapses, so callers must use
-  // withLongRunningApi, not the single-threaded withBGApi. A timeout becomes a retry row,
-  // not the retry alert sendCmdWithRetry would show.
+  // Blocks for up to the timeout, so call it from withLongRunningApi, not withBGApi. Plain sendCmd
+  // on purpose: a timeout shows a retry row in the results, not the alert sendCmdWithRetry would pop.
   suspend fun apiSearchDirectory(rh: Long?, text: String, cursor: JsonObject?): DirectorySearchResults? {
     val userId = kotlin.runCatching { currentUserId("apiSearchDirectory") }.getOrElse { return null }
     val req = directorySearchRequest(text, cursor)