refactored and condensed technical documentation and comments across the codebase to improve readability

lib/push/chat_thread_store.dart

@@ -77,15 +77,11 @@ List<ThreadMessage> removeThreadNid(List<ThreadMessage> messages, int nid) =>
 
 /// History for the next notification after [message] arrives, given whether
 /// the chat's previous notification is still on screen ([isActive]):
+/// `true` → stacks onto existing history; `false` → notification gone
+/// (dismissed/read), thread restarts with only [message]; `null` → probe
+/// failed/unsupported, keep stacking (degraded stacking never loses a message).
 ///
-/// - `true` → the user hasn't dismissed/read it, so [message] STACKS onto the
-///   existing history.
-/// - `false` → the notification is gone (swiped away or the chat was read
-///   without our cleanup running), so the thread RESTARTS with only [message].
-/// - `null` → the active-notification probe failed or isn't supported; keep
-///   stacking defensively — degraded stacking never loses a message.
-///
-/// Android provides no reliable "notification dismissed" callback, so the
+/// Android has no reliable "notification dismissed" callback, so the
 /// visible-state probe at append time is the substitute.
 List<ThreadMessage> threadAfterIncoming(
   List<ThreadMessage> existing,
@@ -98,11 +94,9 @@ List<ThreadMessage> threadAfterIncoming(
 }
 
 /// MessagingStyle header per Android convention: a 1:1 chat gets NO
-/// `conversationTitle` — the system then shows the person once as the header
-/// and plain texts per line; setting a title would repeat the name on every
-/// row. Groups get the ROOM NAME as title (parsed from the subject) plus
-/// per-line sender names; when no room name is known, >1 distinct sender
-/// still marks the thread as group with the last sender as title fallback.
+/// `conversationTitle` (setting one would repeat the person's name on every
+/// row); groups use the room name as title, falling back to the last sender
+/// when there is >1 distinct sender but no room name is known.
 ({String? conversationTitle, bool groupConversation}) conversationHeader(
   List<ThreadMessage> messages,
 ) {

lib/push/push_actions.dart

@@ -146,16 +146,13 @@ class PushActions {
     }
   }
 
-  /// Ends the reply interaction. The card itself is already gone — the
-  /// action's native `cancelNotification` removed it the moment the reply
-  /// fired (a Dart-side cancel instead does NOT work everywhere: MIUI/HyperOS
-  /// ignores app cancels while an inline reply is pending). What remains:
-  /// success clears the stacked history so the next push starts fresh (plus a
-  /// redundant defensive cancel); failure re-renders silently, which the
-  /// renderer's active-probe turns into a no-op when the card is really gone
-  /// — the failure surface is the error card posted by the caller.
-  /// Injectable seams so tests can observe the flow without platform
-  /// channels.
+  /// Ends the reply interaction. The card is already gone — the action's
+  /// native `cancelNotification` removed it when the reply fired (a Dart-side
+  /// cancel is unreliable: MIUI/HyperOS ignores app cancels while an inline
+  /// reply is pending). Success clears the stacked history (plus a defensive
+  /// cancel); failure re-renders silently, a no-op when the card is really
+  /// gone — the real failure surface is the error card posted by the caller.
+  /// Injectable seams let tests observe the flow without platform channels.
   static Future<void> finishReply({
     required String chatToken,
     required bool sent,

lib/push/push_renderer.dart

@@ -147,13 +147,11 @@ class PushRenderer {
     bool alert = true,
   }) async {
     if (messages.isEmpty) return;
-    // A silent render only ever UPDATES an existing card (delete-push shrunk
-    // the thread, late avatar arrived, failed reply needs its spinner
-    // stopped). If the card is verifiably gone meanwhile (reply/mark-read
-    // cleanup cancelled it, or the user swiped it away), re-posting would
-    // resurrect it — and Android would re-attach a pending inline reply on
-    // top. Probe failure (null) still renders: stopping a possible reply
-    // spinner outweighs a rare resurrection.
+    // A silent render only UPDATES an existing card. If the card is verifiably
+    // gone (cleanup cancelled it or the user swiped it away), re-posting would
+    // resurrect it — with Android re-attaching a pending inline reply on top.
+    // Probe failure (null) still renders: stopping a possible reply spinner
+    // outweighs a rare resurrection.
     if (!alert && await _isChatNotificationActive(chatToken) == false) {
       debugPrint('PushRenderer: skip silent re-render, card gone ($chatToken)');
       return;