Improve documentation.

Author: anthony-tuininga

doc/src/api_manual/cursor.rst

@@ -263,19 +263,20 @@ Cursor Methods
     available from a PL/SQL block or procedure without the use of OUT ref
     cursor parameters. The PL/SQL block or procedure opens the cursors and
     marks them for return to the client using the procedure
-    dbms_sql.return_result. Cursors returned in this fashion should not be
-    closed. They will be closed automatically by the parent cursor when it is
-    closed. Closing the parent cursor will invalidate the cursors returned by
-    this method.
+    dbms_sql.return_result. In python-oracledb Thick mode, closing the parent
+    cursor will result in the automatic closure of the implicit result set
+    cursors. See :ref:`implicitresults`.
+
+    This method is only available for Oracle Database 12.1 (or later). For
+    python-oracledb :ref:`Thick <enablingthick>` mode, Oracle Client 12.1 (or
+    later) is additionally required.
 
     .. note::
 
-        The DB API definition does not define this method and it is only
-        available for Oracle Database 12.1 (both client and server must be at
-        this level or higher). It is most like the DB API method nextset(), but
-        unlike that method (which requires that the next result set overwrite
-        the current result set), this method returns cursors which can be
-        fetched independently of each other.
+        The DB API definition does not define this method. It is most like the
+        DB API method nextset(), but unlike that method (which requires that
+        the next result set overwrite the current result set), this method
+        returns cursors which can be fetched independently of each other.
 
 .. method:: Cursor.parse(statement)
 

doc/src/user_guide/appendix_b.rst

@@ -304,6 +304,22 @@ and UROWID database types. In python-oracledb Thick and Thin modes, comparison w
 the type ``oracledb.ROWID`` (defined in the Python DB API) will match both ROWID and
 UROWID database types.
 
+.. _implicitresultsdiff:
+
+Implicit Results in Thin and Thick Modes
+========================================
+
+In python-oracledb Thick mode, the parent cursor that is used to get the
+:ref:`implicit results <implicitresults>` must remain open until all of the
+implicit result sets have been fetched or until the application no longer
+requires them. Closing the parent cursor before all the implicit result sets
+have been fetched will result in the automatic closure of the implicit result
+set cursors.
+
+In python-oracledb Thin mode, there is no requirement to leave the parent
+cursor open when fetching implicit result sets. The parent cursor and implicit
+cursors are independently handled in Thin mode.
+
 .. _stmtcaching:
 
 Statement Caching in Thin and Thick Modes

doc/src/user_guide/plsql_execution.rst

@@ -260,7 +260,9 @@ which may be much slower:
             break
         print(text_var.getvalue())
 
-Implicit results
+.. _implicitresults:
+
+Implicit Results
 ----------------
 
 Implicit results permit a Python program to consume cursors returned by a
@@ -297,6 +299,18 @@ Data from both the result sets are returned::
     (1000, 1, 'BOOKS')
     (2000, 2, 'FURNITURE')
 
+When using python-oracledb Thick mode, you must leave the parent cursor open
+until all of the implicit result sets have been fetched or until your
+application no longer requires them. Closing the parent cursor before
+fetching all of the implicit result sets will result in the closure of the
+implicit result set cursors. If you try to fetch from an implicit result set
+after its parent cursor is closed, the following error will be thrown::
+
+    DPI-1039: statement was already closed
+
+Note that the requirement mentioned above is not applicable for
+python-oracledb Thin mode. See :ref:`implicitresultsdiff`.
+
 .. _ebr:
 
 Edition-Based Redefinition (EBR)

doc/src/user_guide/tuning.rst

@@ -259,10 +259,15 @@ Avoiding Premature Prefetching
 
 There are two cases that will benefit from setting ``prefetchrows`` to zero:
 
-* When passing REF CURSORS *into* PL/SQL packages.  Setting ``prefetchrows`` to
-  0 can stop rows being prematurely (and silently) fetched into the
-  python-oracledb internal buffer, making those rows unavailable to the PL/SQL
-  code that receives the REF CURSOR.
+* When passing a python-oracledb cursor *into* PL/SQL.  Setting
+  ``prefetchrows`` to 0 can stop rows being prematurely (and silently) fetched
+  into the python-oracledb internal buffer, making those rows unavailable to
+  the PL/SQL REF CURSOR parameter::
+
+    refcursor = connection.cursor()
+    refcursor.prefetchrows = 0
+    refcursor.execute("select ...")
+    cursor.callproc("myproc", [refcursor])
 
 * When querying a PL/SQL function that uses PIPE ROW to emit rows at
   intermittent intervals.  By default, several rows needs to be emitted by the