Add clarification to the driver close and closeAsync methods (#1537) (#…

…1541)

driver/src/main/java/org/neo4j/driver/Driver.java

@@ -130,6 +130,10 @@ public interface Driver extends AutoCloseable {
      * Close all the resources assigned to this driver, including open connections and IO threads.
      * <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.
      */
     @Override
     void close();
@@ -139,6 +143,10 @@ public interface Driver extends AutoCloseable {
      * <p>
      * 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.
      *
      * @return a {@link CompletionStage completion stage} that represents the asynchronous close.
      */