Doc improvements.

Author: anthony-tuininga

doc/src/api_manual/async_connection_pool.rst

@@ -163,8 +163,6 @@ AsyncConnectionPool Attributes
     forces a ping for every :meth:`AsyncConnectionPool.acquire()` and is not
     recommended.
 
-    Prior to cx_Oracle 8.2, the ping interval was fixed at *60* seconds.
-
 .. attribute:: AsyncConnectionPool.soda_metadata_cache
 
     This read-write boolean attribute returns whether the SODA metadata cache

doc/src/api_manual/connection.rst

@@ -219,6 +219,8 @@ Connection Methods
     This function performs a local check. To fully check a connection's health,
     use :meth:`Connection.ping()` which performs a round-trip to the database.
 
+    .. dbapimethodextension::
+
 .. method:: Connection.msgproperties(payload, correlation, delay, exceptionq, expiration, priority)
 
     Returns an object specifying the properties of messages used in advanced
@@ -231,14 +233,18 @@ Connection Methods
 
 .. method:: Connection.ping()
 
-    Pings the database to verify if the connection is valid.
+    Pings the database to verify if the connection is valid. An exception is
+    thrown if it is not, in which case the connection should not be used by the
+    application and a new connection should be established instead.
 
     This function performs a :ref:`round-trip <roundtrips>` to the database, so
     it should not be used unnecessarily.
 
     Note connection pools will perform the same health check automatically,
     based on configuration settings. See :ref:`poolhealth`.
 
+    Also, see :meth:`Connection.is_healthy()` for a lightweight alternative.
+
     .. dbapimethodextension::
 
 .. method:: Connection.prepare()

doc/src/api_manual/connection_pool.rst

@@ -18,7 +18,7 @@ In python-oracledb, the type `pool` will show the class `oracledb.ConnectionPool
 This only affects the name.
 
 The following code will continue to work providing backward compatibility with
-cx_Oracle:
+the obsolete cx_Oracle driver:
 
 .. code-block:: python
 

doc/src/api_manual/defaults.rst

@@ -83,12 +83,11 @@ Defaults Attributes
     This can help avoid issues with converting numbers from Oracle Database's
     decimal format to Python's binary format.
 
-    An output type handler such as previously required in cx_Oracle (see
-    `return_numbers_as_decimals.py <https://github.com/oracle/python-cx_Oracle/
-    blob/main/samples/return_numbers_as_decimals.py>`__) can alternatively be
-    used to adjust the returned type.  If a type handler exists and returns a
-    variable (that is, ``cursor.var(...)``), then that return variable is used.
-    If the type handler returns *None*, then the value of
+    An output type handler such as previously required in the obsolete
+    cx_Oracle driver can alternatively be used to adjust the returned type.  If
+    a type handler exists and returns a variable (that is,
+    ``cursor.var(...)``), then that return variable is used.  If the type
+    handler returns *None*, then the value of
     ``oracledb.defaults.fetch_decimals`` is used to determine whether to return
     ``decimal.Decimal`` values.
 
@@ -102,13 +101,11 @@ Defaults Attributes
     LOBs are larger than 1 GB, then this attribute should be set to *True* and
     the LOBs should be streamed.  See :ref:`lobdata`.
 
-    An output type handler such as the one previously required in cx_Oracle
-    (see `return_lobs_as_strings.py <https://github.com/oracle/
-    python-cx_Oracle/blob/main/samples/return_lobs_as_strings.py>`__) can
-    alternatively be used to adjust the returned type.  If a type handler
-    exists and returns a variable (that is, `cursor.var(...)`), then that
-    return variable is used. If the type handler returns *None*, then the value
-    of ``oracledb.defaults.fetch_lobs`` is used.
+    An output type handler such as the one previously required in the obsolete
+    cx_Oracle driver can alternatively be used to adjust the returned type.  If
+    a type handler exists and returns a variable (that is, `cursor.var(...)`),
+    then that return variable is used. If the type handler returns *None*, then
+    the value of ``oracledb.defaults.fetch_lobs`` is used.
 
     The value of ``oracledb.defaults.fetch_lobs`` does not affect LOBs returned
     as OUT binds.

doc/src/api_manual/deprecations.rst

@@ -11,8 +11,9 @@ and is no longer available in python-oracledb. The most recent deprecated and
 desupported features are listed first.
 
 The previous cx_Oracle deprecation announcements remain in force for
-python-oracledb.  The relevant functionality may be removed in a future version
-of python-oracledb.
+python-oracledb. The relevant functionality may be removed in a future version
+of python-oracledb. The cx_Oracle driver itself is obsolete and should not be
+used for new development.
 
 .. list-table-with-summary:: Deprecated in python-oracledb 3.0
     :header-rows: 1
@@ -23,7 +24,8 @@ of python-oracledb.
     * - Name
       - Comments
     * - Parameter ``pool`` of :meth:`oracledb.connect()` and :meth:`oracledb.connect_async()`
-      - Use :meth:`ConnectionPool.acquire()` instead
+      - Use :meth:`ConnectionPool.acquire()`, or make use of the
+        :ref:`connection pool cache <connpoolcache>` instead
 
 .. list-table-with-summary:: Desupported in python-oracledb 2.0
     :header-rows: 1