From 4ba3feb93bcd518e01c220a723cfdc4ba5a3664d Mon Sep 17 00:00:00 2001
From: Dmitriy Tverdiakov <11927660+injectives@users.noreply.github.com>
Date: Tue, 15 Apr 2025 11:30:15 +0100
Subject: [PATCH] docs: Update Driver#close() and Driver#closeAsync()
 documentation (#1634)

The objective is to improve `Driver#close()` and `Driver#closeAsync()` methods documentation and to emphasise that it should be called only when all driver interactions are finished.
---
 driver/src/main/java/org/neo4j/driver/Driver.java | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/driver/src/main/java/org/neo4j/driver/Driver.java b/driver/src/main/java/org/neo4j/driver/Driver.java
index b8f6dc2b17..da6e0490d7 100644
--- a/driver/src/main/java/org/neo4j/driver/Driver.java
+++ b/driver/src/main/java/org/neo4j/driver/Driver.java
@@ -131,9 +131,9 @@ public interface Driver extends AutoCloseable {
      * <p>
      * This operation works the same way as {@link #closeAsync()} but blocks until all resources are closed.
      * <p>
-     * Please note that this method is intended for graceful shutdown only and expects that all driver interactions have
-     * either been finished or no longer awaited for. Pending driver API calls may not be completed after this method is
-     * invoked.
+     * Since this method is intended for graceful shutdown only, it is strongly recommended to finish interaction with
+     * all driver resources (like sessions, transactions, results, etc.) before invoking this method. Not doing this may
+     * result in unspecified behaviour, including leaving driver execution unfinished indefinitely.
      */
     @Override
     void close();
@@ -144,9 +144,9 @@ public interface Driver extends AutoCloseable {
      * This operation is asynchronous and returns a {@link CompletionStage}. This stage is completed with
      * {@code null} when all resources are closed. It is completed exceptionally if termination fails.
      * <p>
-     * Please note that this method is intended for graceful shutdown only and expects that all driver interactions have
-     * either been finished or no longer awaited for. Pending driver API calls may not be completed after this method is
-     * invoked.
+     * Since this method is intended for graceful shutdown only, it is strongly recommended to finish interaction with
+     * all driver resources (like sessions, transactions, results, etc.) before invoking this method. Not doing this may
+     * result in unspecified behaviour, including leaving driver execution unfinished indefinitely.
      *
      * @return a {@link CompletionStage completion stage} that represents the asynchronous close.
      */