Doc updates.

Author: anthony-tuininga

doc/src/api_manual/async_connection.rst

@@ -69,6 +69,15 @@ AsyncConnection Methods
 
     Closes the connection.
 
+    .. note::
+
+        Asynchronous connections are not automatically closed at the end of
+        scope. This is different to synchronous connection
+        behavior. Asynchronous connections should either be explicitly closed,
+        or have been initially created via a `context manager
+        <https://docs.python.org/3/library/stdtypes.html#context-manager-types>`__
+        ``with`` block.
+
 .. method:: AsyncConnection.commit()
 
     Commits any pending transaction to the database.

doc/src/api_manual/async_connection_pool.rst

@@ -57,22 +57,23 @@ AsyncConnectionPool Methods
 
 .. method:: AsyncConnectionPool.release(connection, tag=None)
 
-    Releases the connection back to the pool now, rather than whenever
-    ``__del__`` is called. The connection will be unusable from this point
-    forward; an Error exception will be raised if any operation is attempted
-    with the connection. Any cursors or LOBs created by the connection will
-    also be  marked unusable and an Error exception will be raised if any
-    operation is attempted with them.
-
-    Internally, references to the connection are held by cursor objects,
-    LOB objects, and so on. Once all of these references are released, the
-    connection itself will be released back to the pool automatically. Either
-    control references to these related objects carefully or explicitly
-    release connections back to the pool in order to ensure sufficient
-    resources are available.
+    Releases the connection back to the pool now. The connection will be
+    unusable from this point forward. An Error exception will be raised if any
+    operation is attempted with the connection. Any cursors or LOBs created by
+    the connection will also be marked unusable and an Error exception will be
+    raised if any operation is attempted with them.
 
     The ``tag`` parameter is ignored in python-oracledb Thin mode.
 
+    .. note::
+
+        Asynchronous connections are not automatically closed at the end of
+        scope. This is different to synchronous connection
+        behavior. Asynchronous connections should either be explicitly
+        released, or have been initially created via a `context manager
+        <https://docs.python.org/3/library/stdtypes.html#context-manager-types>`__
+        ``with`` statement.
+
 .. _asyncconnpoolattr:
 
 AsyncConnectionPool Attributes

doc/src/api_manual/async_cursor.rst

@@ -106,10 +106,18 @@ AsyncCursor Methods
 
 .. method:: AsyncCursor.close()
 
-    A synchronous method that closes the cursor now, rather than whenever
-    ``__del__`` is called. The cursor will be unusable from this point
-    forward; an Error exception will be raised if any operation is attempted
-    with the cursor.
+    A synchronous method that closes the cursor now. The cursor will be
+    unusable from this point forward. An Error exception will be raised if any
+    operation is attempted with the cursor.
+
+    .. note::
+
+        Asynchronous cursors are not automatically closed at the end of
+        scope. This is different to synchronous cursor behavior. Asynchronous
+        cursors should either be explicitly closed, or have been initially
+        created via a `context manager
+        <https://docs.python.org/3/library/stdtypes.html#context-manager-types>`__
+        ``with`` block.
 
 .. method:: AsyncCursor.execute(statement, parameters=None, ** keyword_parameters)
 

doc/src/user_guide/asyncio.rst

@@ -32,6 +32,13 @@ The asynchronous API classes are :ref:`AsyncConnection <asyncconnobj>`,
 :ref:`AsyncConnectionPool <asyncconnpool>`,
 :ref:`AsyncCursor <asynccursorobj>`, and :ref:`AsyncLOB <asynclobobj>`.
 
+Unlike their synchronous counterparts, asynchronous connections and cursors are
+not automatically closed at the end of scope. These asynchronous resources
+should either be explicitly closed, or have been initially created via a
+`context manager
+<https://docs.python.org/3/library/stdtypes.html#context-manager-types>`__
+``with`` block.
+
 .. note::
 
     Concurrent programming with asyncio is only supported in
@@ -105,6 +112,8 @@ when they are no longer needed, for example:
     cursor.close()
     await connection.close()
 
+Note asynchronous connections are not automatically closed at the end of
+scope. This is different to synchronous connection behavior.
 
 .. _asyncconnpool:
 
@@ -165,7 +174,12 @@ executed using the asynchronous methods :meth:`AsyncCursor.execute()` or
 :meth:`AsyncCursor.executemany()`. Rows can be iterated over, or fetched using
 one of the methods :meth:`AsyncCursor.fetchone()`,
 :meth:`AsyncCursor.fetchone()`, :meth:`AsyncCursor.fetchmany()`, or
-:meth:`AsyncCursor.fetchall()`.
+:meth:`AsyncCursor.fetchall()`.  Note that explicitly opened asynchronous
+cursors are not automatically closed at the end of scope. This is different to
+synchronous behavior.  Asynchronous cursors should either be explicitly closed,
+or have been initially created via a `context manager
+<https://docs.python.org/3/library/stdtypes.html#context-manager-types>`__
+``with`` block.
 
 You can also use shortcut methods on the :ref:`asyncconnobj` object such as
 :meth:`AsyncConnection.execute()` or