Final tweaks to documentation on enable_thin_mode().

Author: anthony-tuininga

doc/src/api_manual/module.rst

@@ -1896,16 +1896,15 @@ Oracledb Methods
 
     Makes python-oracledb be in Thin mode. After this method is called, Thick
     mode cannot be enabled. If python-oracledb is already in Thick mode, then
-    calling ``enable_thin_mode()`` will fail. If connections have already been
-    opened, or a connection pool created, in Thin mode, then calling
-    ``enable_thin_mode()`` is a no-op.
+    calling ``enable_thin_mode()`` will fail. If Thin mode connections have
+    already been opened, or a connection pool created in Thin mode, then
+    calling ``enable_thin_mode()`` is a no-op.
 
     Since python-oracledb defaults to Thin mode, almost all applications do not
     need to call this method. However, because it bypasses python-oracledb's
     internal mode-determination heuristic, it may be useful for applications
-    that are using :ref:`standalone connections <standaloneconnection>` in
-    multiple threads to concurrently create connections when the application
-    starts.
+    with multiple threads that concurrently create :ref:`standalone connections
+    <standaloneconnection>` when the application starts.
 
     See :ref:`enablingthin` for more information.
 

doc/src/release_notes.rst

@@ -38,7 +38,7 @@ Thin Mode Changes
     python-oracledb Thin mode without waiting for an initial connection to be
     succesfully established. Since python-oracledb defaults to Thin mode, this
     method is mostly useful for applications with multiple threads concurrently
-    creating connections to different databases when the application starts
+    creating connections to databases when the application starts
     (`issue 408 <https://github.com/oracle/python-oracledb/issues/408>`__).
 #)  Fixed bug when calling :meth:`Connection.gettype()` for a type that exists
     but on which the user has insufficient privileges to view

doc/src/user_guide/initialization.rst

@@ -317,28 +317,34 @@ going to be used.  In one special case, you may wish to explicitly enable Thin
 mode to prevent Thick mode from being enabled later.
 
 To allow application portability, the driver's internal logic allows
-applications to initally attempt
-:ref:`standalone connection <standaloneconnection>` creation in Thin mode, but
-then lets them :ref:`enable Thick mode <enablingthick>` if that connection is
-unsuccessful.  An example is when trying to connect to an Oracle Database that
-turns out to be an old version that requires Thick mode.  This heuristic means
-Thin mode is not enforced until the initial connection is successful.  Since
-all connections must be the same mode, any second and subsequent concurrent
-Thin mode connection attempts will wait for the initial standalone connection
-to succeed, meaning the driver mode is no longer potentially changeable to
-Thick mode.
-
-This heuristic delay does not impact:
-
-- Single-threaded applications using standalone connections.
+applications to initally attempt :ref:`standalone connection
+<standaloneconnection>` creation in Thin mode, but then lets them :ref:`enable
+Thick mode <enablingthick>` if that connection is unsuccessful.  An example is
+when trying to connect to an Oracle Database that turns out to be an old
+version that requires Thick mode.  This heuristic means Thin mode is not
+enforced until the initial connection is successful.  Since all connections
+must be the same mode, any second and subsequent concurrent Thin mode
+connection attempt will wait for the initial standalone connection to succeed,
+meaning the driver mode is no longer potentially changeable to Thick mode.
+
+If you have multiple threads concurrently creating standalone Thin mode
+connections, you may wish to call :meth:`oracledb.enable_thin_mode()` as part
+of your application initialization. This is not required but avoids the mode
+determination delay.
+
+The mode determination delay does not affect the following cases, so calling
+:meth:`~oracledb.enable_thin_mode()` is not needed for them:
+
+- Single-threaded applications using :ref:`standalone connections
+  <standaloneconnection>`.
 - Single or multi-threaded applications using
   :ref:`connection pools <connpooling>` (even with ``min`` of 0).
-- Applications that have already called :func:`oracledb.init_oracle_client()`.
 
-In the case that you want to open multiple standalone Thin mode connections in
-multiple threads, you may wish to force Thin mode by calling
-:meth:`oracledb.enable_thin_mode()` as part of your application initialization.
-This avoids the mode heuristic delay. For example:
+The delay also does not affect applications that have already called
+:func:`oracledb.init_oracle_client()` to enable Thick mode.
+
+To explicitly enable Thin mode, call :meth:`~oracledb.enable_thin_mode()`, for
+example:
 
 .. code-block:: python