Document necessary try-catch blocks and remove redundant ones

Author: p123-stack

src/Bolt/BoltConnection.php

@@ -315,6 +315,9 @@ public function __destruct()
 
     public function close(): void
     {
+        // Graceful cleanup: GOODBYE/DISCARD may fail if connection already broken.
+        // Must catch to ensure unset($this->boltProtocol) executes,
+        // preventing pool from reusing broken connections.
         try {
             if ($this->isOpen()) {
                 if ($this->isStreaming()) {
@@ -346,15 +349,7 @@ public function close(): void
     public function invalidate(): void
     {
         $this->subscribedResults = [];
-        try {
-            $this->connection->disconnect();
-        } catch (Throwable $e) {
-            $this->logger?->log(LogLevel::WARNING, 'Failed to disconnect during invalidation', [
-                'exception' => $e->getMessage(),
-                'type' => $e::class,
-            ]);
-        }
-
+        $this->connection->disconnect();
         unset($this->boltProtocol);
     }
 
@@ -444,6 +439,7 @@ public function assertNoFailure(Response $response): void
 
     /**
      * Discard unconsumed results - sends DISCARD to server for each subscribed result.
+     * Try-catch prevents DISCARD failures from breaking cleanup chain in Session.close().
      */
     public function discardUnconsumedResults(): void
     {

src/Bolt/BoltResult.php

@@ -105,11 +105,15 @@ public function consume(): array
 
     private function fetchResults(): void
     {
+        // Catch socket/connection errors during PULL. Convert BoltConnectException to Neo4jException
+        // so Session retry logic can detect and handle connection failures (triggers routing table refresh).
         try {
             $meta = $this->connection->pull($this->qid, $this->fetchSize);
         } catch (BoltConnectException $e) {
             // Close connection on socket errors
             $this->connection->invalidate();
+            // Convert to Neo4jException with NotALeader code so Session.executeStatementWithRetry()
+            // and Session.retry() can catch it and clear routing table for automatic failover recovery.
             throw new Neo4jException([Neo4jError::fromMessageAndCode('Neo.ClientError.Cluster.NotALeader', 'Connection error: '.$e->getMessage())], $e);
         }
 
@@ -168,9 +172,10 @@ public function discard(): void
         try {
             $this->connection->discard($this->qid === -1 ? null : $this->qid);
         } catch (BoltConnectException $e) {
+            // Connection already broken if DISCARD fails. Invalidate to prevent pool from reusing it.
+            // Don't rethrow: this is called from __destruct() where exceptions don't propagate properly.
+            // Connection will be detected as broken on next operation when pool tries to reuse it.
             $this->connection->invalidate();
-            // Ignore connection errors during discard - connection is already broken
-            // The Neo4jException will be thrown when the next operation is attempted
         }
     }
 }

src/Bolt/Session.php

@@ -248,8 +248,29 @@ private function shouldClearRoutingTable(Neo4jException $e): bool
      *
      * @return SummarizedResult The result of the statement
      */
+
+    /**
+     * Execute instant transaction (session.run) with automatic retry on connection/routing errors.
+     *
+     * PURPOSE:
+     * - Handles transient failures transparently to user: connection timeouts, server unavailable, etc.
+     * - Supports cluster failover: when server goes down, clears routing table and retries on different node
+     * - Distinguishes errors: retries on connection/routing issues but fails immediately on client errors (syntax, auth)
+     * - Improves reliability: 3 retry attempts with fresh routing table each time = high availability
+     *
+     * EXAMPLE: User calls session.run("CREATE (n)") during cluster failover:
+     *   Attempt 1: Node A is leader → "NotALeader" (stepping down) → Clear routing table
+     *   Attempt 2: Node B elected leader → "Connection timeout" (election in progress) → Retry
+     *   Attempt 3: Cluster stable → Query succeeds
+     *   User sees: Query succeeded transparently (no exception, no manual retry needed)
+     *
+     * WHY THIS IS CRITICAL FOR DRIVERS:
+     * - All Neo4j drivers (Java, Python, JavaScript) have this pattern
+     * - Without it: user must manually retry or wrap every session.run() in try-catch
+     * - With it: driver handles recovery automatically = better UX and reliability
+     */
     private function executeStatementWithRetry(Statement $statement, TransactionConfiguration $config): SummarizedResult
-    {
+    {    // Retry instant transactions up to 3 times on connection/routing errors; catch distinguishes retryable errors from client errors (syntax, auth) and clears routing table for cluster failover.
         $maxRetries = 3;
         $retries = 0;